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Introduction 



As we move into a world where mobile devices are becoming the primary mechanism for people 
to connect with the Internet, it should come as no surprise that the ability to develop apphcations 
for mobile devices is becoming a sought after skill. We also have very strong vendor competition 
in the space, resulting in a marketplace filled with a variety of devices. 

We see vendors promoting development tools and marketplaces for their own devices, 
attempting to create software ecosystems around their products. For the most part, the stratégy is 
working too (for some vendors more than others). Developers are using those tools and creating 
"native" applications for a particular device, and then having to rebuild large portions of their 
applications to target each different device. 

For some companies building mobile applications, this is an acceptable approach. It is, 
however, one that is entirely unsustainable for the longer term. Consider that each company with 
a web product will be expected to provide both a desktop web application and suitable mobile 
clients for multiple devices in the next fewyears (if not months). Then consider the number of 
software developers - people like you and me, that there are in the world. Do we have the 
required resources to meet this demand? I would venture not. There must be a better way. And 
there is. 

Building mobile web apps is this better way. It is an approach to mobile app development 
that when done right, will have you rewriting a lot less code to target the variety of devices that 
exist in the marketplace. This book focuses on writing mobile web apps for Android, but in reality 
many of the concepts can be easily ported across to other mobile devices (which is the whole 
point). 



Whaťs a Mobile Web App? 

A mobile web app is an application that is built with the core client web technologies of HTML, 
CSS, and JavaScript, and is specifically designed for mobile devices. Helping mobile web apps get 
a bit of attention are the trends toward HTML5 and CSS3 — the latest "versions" of two of the 
technologies. We explore both HTML5 and CSS3 in detail in the book, along with a lot of 
JavaScript. 

JavaScript is the language that many developers love to hate. Some don't even regard it as a 
programming language at all. However, JavaScript is here for the long haul, and is likely to be one 
of the most in demand skillsets for the next five years. 



Which Technologies Are Used in This Book? 

In the book, we work through lots (and lots) of JavaScript code. There's obviously quite a bit of 
HTML and CSS there too, but JavaScript really is the language of mobile web app development. 

If you haven't worked with JavaScript in the past, we don't completely drop you in at the 
deep end, but we would recommend getting hold of some learning materials, as this isn't a 
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JavaScript fundamentals book. We also make extensive use of the excellentjQuery JavaScript 
library to make life generally easier during development. If that is something that is new to you, 
we recommend having a jQuery tutoriál or two handy as well. If you Jiave experience with 
Prototype, MooTools, or another of jQuery's "competitors," thenyou should be able to adapt the 
sample code in the book with relative ease. 

In terms of mobile web apps (and other JavaScript-rich web apps), learning how to structure 
your applications for readability and maintainability is important. This is one of the reasons that 
we have chosen to work through a couple of small application-sized projects in the book rather 
than small code-snippets showing particular functionality. This will allowyou to become familiar 
with the different technical aspects of mobile web app development, and also gain an 
understanding of how you might effectively put a real-world mobile web application together. 

If you are already familiar with web application development, this book should make the 
transition to mobile web app development simple. If, however, you are coming from a mobile 
application development perspective, and are looking to explore the web app approach, having 
those extra learning materials will make a big difference. 



Whaťs in This Book 

This book is structured around two application samples that will teach you the various aspects of 
mobile web app development. Chapters 2-6 deal with the first mini application of a simple "To 
Do List", and Chapters 8-12 guide you through the beginnings of building a simple location- 
aware game. 

In and around these two "main meals" we have three "snack" chapters. Chapter 1 is focused 
on getting you up and running with the basic concepts for writing Android web apps. Chapter 7 is 
a short look at working with interactivity and the fJTMLS canvas. And finally, Chapter 13 takés a 
look at some of the things that might be coming our way in the world of mobile apps. 
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Getting Started 



Weicome to the wonderful worid of web app development for Android. Over the course 
of the book we will walk through the process of building mobile web apps. While 
targeted primarily at Android, most (if not all) of the code will work just as weil on 
Chromé OS. Actually, the reusability of the application code will go beyond Chromé 
OS— the code from this book shouid be able to run on any device that provides a 
WebKit-based browser. If you aren't familiar with WebKit or Chromé OS at this stage, 
don't worry— you will be by the end of the book. 

In this chapter, we will go through a few topics at a high level so you can start building 
applications as quickly as possible: 

■ An overview of the platform capabilities of Android 

■ Which of those capabilities we can access through the web browser 
(either by default or by using bridging frameworks such as PhoneGap) 

■ Configuring a development environment for coding the samples in this 
book and your own applications 

■ An overview of the tools that come with the Android development kit, 
and some supporting tools to assist you in building web apps 

Understanding Android Platform Capabilities 

The Android operating systém (OS) was designed as a generic OS for mobile devices 
(including smartphones and tablet PCs). The pian was that Android wouid serve multiple 
device manufacturers as their device OS, which the manufacturers couid then customize 
and build upon. For the most part this vision has been realized, and a number of 
manufacturers have built devices that ship with Android installed and have also become 
part of the Open Handset Alliance (http : //openhandsetalliance . com). 

Android, however, is not the oniy mobile OS available, and this means that a native 
Android application wouId have to be rewritten to support another (non-Android) mobile 
device. This leads to having to manage the ongoing development of mobile applications 
for each of the platforms that you wish to support. While the large companies of the 
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worid can afford to do this, it can be difficult for a smaller organization or startup. Here 
in lies the attraction of developing mobile web apps— whte the application code once 
and have it work on multiple devices. 

This section of the bool< will outline the current features of the Android OS, and if 
relevant whether you can access that functionality when building web applications. 

For those who wouid prefer a summary of the systenn capabilities and what you can 
actually access via the browser or a bridging framework, then head straight to Table 1- 
2, toward the end of this section. 



BRIDGING FRAMEWORKS 



A bridging framework provides developers a technique for building web applications that can be deployed 
to mobile devices. The framework also provides access to portions of the native device capabilities (such 
as the accelerometer and camera) through a wrapper (usually JavaScript) to the native API. 

During the course of the book, we will work through some examples that use PhoneGap 

(http : //phonegap . com) to bridge to some of this native functionality. While PhoneGap was one of the 

first, there are many more bridging frameworks available. In this book, though, we focus on PhoneGap, as 

it provides a simple and lightweight approach for wrapping a mobile web application for native 

deployment. 

For more Information on the various mobile web app frameworks, I have written a couple of different blog 
posts on the topič. In particular, the following post has some great comments from contributors on the 
projects that help to show their areas of strength: http : //distractable . net/coding/iphone- 
android-web-application-frameworks. 

While I wouId have loved to taik more about each in this book, the focus here is on building mobile web 
applications. From my perspective, these are applications that can be deployed to the Web and accessed 
via a device's browser. The addition of a bridging framework shouid be an optional extra rather than a 
requirement Given this particular use case, PhoneGap is a clear winner. 



Device Connectivity 

While as consumers we are all probably starting to take the connectivity options of our 
own mobile devices for granted, iťs important not to do this as a mobile developer (web 
app or native). If mobile applications are built assuming that a connection to the Web is 
aiways available, then this limits the usefulness of an application when connectivity is 
limited— which is more often than you might think. 

Understanding that your application will have varying levels of connectivity at different 
times is very important for creating an application that gives a satisfying user experience 
at all times. 

In very simple terms, a mobile device can have three levels of connectivity from a web 
perspective: 



■ A high-bandwidth connection (e.g., WiFi) 



■ A lower-bandwidth connection (e.g., 3G) 

■ Limited or no connectivity (offline) 

At present, when building a pure web app, you can really oniy detect whetiner 
you Inave connectivity or not (without actually attempting downioads or the like 
to test connection speed). TInis is different from building native Android 
applications, as these applications can access native APls that provide 
information regarding the device's current connection type and quality. 

In Chapter 5, we will investigate features in the HTML5 API for enabling your 
applications to work weil offline, and in Chapter 9 we'll explore examples using 
bridging franneworks to access some of the native connectivity detection. 



Touch 

One of the features that helped the current breed of nnobile devices break away from the 
old is the touch interface. Depending on the version of Android, at a native level you will 
either have access to multitouch events or just single-touch events. Web apps, on the 
other hand, onIy allow access to single-touch events at this stage. 

NOTE: Not having multitouch event support for web apps certainiy gives native applications an 
edge when it comes to application Ul implementation. This will almost certainiy change in the 
future, but for some time we will likely have a situation where some Android devices support 
multitouch for web apps and others don't. 



It will be important at least for the next couple of years to aiways code primarily for single-touch 
and offer improved functionality (time permitting) for those devices that support multitouch 
events in the web browser. 



We will start exploring touch events in some depth in Chapter 7. 




Geolocation 

The Android OS supports geographical location detection through various different 
implementations, including GPS (Global Positioning System) and cell-tower 
triangulation, and additionally Internet services that use techniques such as IP sniffing to 
determine location. At a native API level, geolocation is implemented in the 
android. location package (see 

http://developer.android.com/reference/android/location/package-summary.html), 
and most bridging frameworks exposé this functionality from the native API. 

Since HTML5 is gaining acceptance and has been partially implemented (full 
implementation will come once the specification is finalized in the next couple of years). 



we can also access location information directly in the browser, without the need for a 
bridging framework. This is done by using the HTML5 Geolocation API 
(www.w3.org/TR/geolocation-API). For more information on the HTIVILS Geolocation API, 
see Ghapter 6. 

Hardware Sensors 

One of the coolest things about modem smartphones is that they come equipped with a 
range of hardware sensors, and as technology becomes more pervasive this is oniy 
going to increase. One of the most widespread sensors currently is the three-axis 
accelerometer, which allows developers to write software that tracks user interaction in 
innovative ways. The list of hardware sensors that the Android OS can currently interact 
with goes beyond the accelerometer, however, and a quick visit to the current hardware 
sensor API reference for native development reveals an impressive list of sensors that 
are aiready supported in the native API (see 

http : //developer . android . com/ref erence/android/hardware/Sensor . html). Table 1-1 
lists the various sensors and provides information on whether access to the sensor is 
currently supported with the bridging framework PhoneGap. If you are not familiar with 
one of the sensors listed, then Wikipedia has some excellent information - simply search 
on the sensor name. Note that while the Android SDK (software development kit) 
supports a number of hardware sensors, most are not accessible via mobile web apps 
(yet). 

Table 1 -1 . Sensors Supported by the Android SDK 



Sensor 


PhoneGap Support 


Acceleronneter 


Yes 


Gyroscope 


No 


Light 


No 


Magnetic field 


No 


Orientation 


Yes 


Pressure 


No 


Proximity 


No 


Temperature 


Yes 



One of the most compelling arguments to go with native development over web 
development is to gain access to the vast array of sensors that will continue to be added 
to mobile devices as technology progresses. While definitely a valid argument, building a 
web app in conjunction with a bridging framework can allow you to access some of the 
more commoniy used and available sensors. 



Additionally, PhoneGap is an open source framework, and the ability to write plug-ins is 
provided (aithough hard to find good information on), so iťs definitely possible to access 
additional sensors. 

Local Databases and Storage 

Mobile devices have for a long time supported local storage in one form or another, but 
in more recent times we have started to see standardized techniques (and technology 
selection) for implementing storage. Certainiy at a native API level, Android implements 
support for SQLite (http://sqlite.org) through the android. database.sqlite package 
(see http://developer.android.com/reference/android/database/sqlite/package- 
summary.html). 

SQLite is quickly becoming the de facto standard for embedded databases, and this is 
true when it comes to innplementing local storage and databases for web technologies. 
Having access to a lightweight database such as SQLite on the client makes it possible 
to create applications that can both store and cache location copies of information that 
might normally be stored on a remote server. 

Two new, in-progress HTML5 standards provide mechanisms for persisting data without 
needing to interact with any external services apart from JavaScript. These new APls, 
HTML5 Web Storage (http://dev.w3.org/html5/webstorage) and Web SQL Database 
(http://dev.w3.org/html5/webdatabase), provide some excellent tools to help make 
your applications work in offline situations. We explore these APls in some depth in 
Chapter 3. 

Camera Support 

Before touch became one of the primary sought-after features for mobile devices, 
having a reasonable camera was certainiy something that influenced a purchase 
decision. This is reflected in the variety of native applications that actually make use of 
the camera. At a native level, access to the camera is implemented through the 
android. hardware. Camera class (see 

http : //developer .android . com/ref erence/android/hardware/Camera . html); however, it 
is not yet accessible in the browser— but the HTML Media Capture specification is in 
progress (see www.w3.0rg/TR/capture-api). 

Until such time that the specification is finalized, however, bridging frameworks can 
provide web applications access to the camera and picture library on the device. 

Messaging and Push Notifications 

In Android 2.2, a service called Cloud to Device Messaging (C2DM) 
(http://code.google.com/android/c2dm/index.html) has been implemented at the 
native level. This service allows native developers to register their applications for what 
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are commonly known as push notifications, whereby a mobile user will be notified when 
something is new or has changed. 

It will be some time before pusli notifications are implemented in browsers, as a worl<ing 
group has oniy recently been announced to discuss and provide a recomnnendation on 
this particular area (see www.w3.org/2010/06/notification-charter). 

Unfortunately, with C2DM being reasonably new, it will probably be some time before 
the bridging frameworl<s implement this for Android. 



WebKit Web Browser 

The Android OS implements a WebKit-based browser. WebKit (http://webkit.org) is an 
open source browser engine that has reached a notable level of adoption for desl<top 
and mobile browsers alil<e. The WebKit engine powers many popular browsers like 
Chromé and Safari on the desktop, and mobile Safari and the native Android browser in 
mobile (to name a few). This alone is a great reason to build web applications for mobile 
rather than native applications. As both Android and the iPhone implement a native 
WebKit browser (IVlobile Safari is WebKit at its core), you can target both devices very 
simply if you consider WebKit as your common denominator. 

Why is having WebKit in common so important? Given HTIVILS and CSS3 are both still 
emerging specifications, it will probably be a couple of years before web standards are 
concrete and mobile browsers all behave in a consistent way. For now, having WebKit 
as a common element between the two dominant consumer smartphone platforms is a 
huge advantage. As developers, we can build applications that make use of the 
components of HTML5 that are starting to stabilize (and are thus being implemented in 
more progressive browser engines, such as WebKit), and actually have a good chance 
of making those applications work on both an Android handset and an iPhone. Try doing 
that with either native Android Java code or iPhone Objective-C code. 

NOTE: Adoption of WebKit as the "mobile browser of choice" appears to be gaining momentům. 1 

Research In Motion (RIM), the company responsible for BlackBerry, has adopted WebKit and I 

HTML5 in its new BlackBerry Torch. This is good news for mobile web application developers, Á 

and I believe shows the future is in cross-platform web development rather than the current ■ 
trend of native development. 



Process Management 

Process management is handled similarly on Android and iOS devices since Apple's 
release of iOS 4; however, prior to that there was a fairiy significant difference between 
the way Android and iPhone applications behaved when a user "exited" them. On the 
iPhone, once you left an application, it essentially stopped running— which meant there 
really wasn't any ability to do anything in the background. On Android, however, if a user 



left an application (including a web application) without quitting, it wouid continue to 

execute in the background. 

To validate this, we ran the following code on an Android handset to ensure that 
requests were still coming through while the application (in this oase the browser) was 
not the active application. 

<html> 
<body> 

<script type="text/javascript"> 
setInterval(function() { 
var image = new Image(); 

image.src = "images/" + new Date() .getTime() + ".png"; 
}, 1000) j 
</script> 
</body> 
</html> 

Using the JavaScript setinterval call in this context means that an image request (for 
an image that doesn't exist) is issued every second. When the code runs, that image 
request is made to the web server every second (or thereabouts) regardless of whether 
the web browser is the active application or not. Additionally, as the browser on Android 
supports multiple windows being open at once, the request will continue to execute 
even if the browser is active but a different window is selected as the current window. 

Having this kind of background processing ability provides developers some excellent 
opportunities. It is, however, important to make sure our applications are built in such a 
way that when in the background, applications aren't downioading unnecessary 
information or consuming excessive battery power. 

Android OS Feature Summary 

Table 1-2 shows a matrix of device features, the Android version from which they are 
supported, and whether they can be accessed in the browser. In some cases the browser 
support column uses the term bridge. This refers to the use of bridging frameworks (such 
as PhoneGap, Rhodes, etc.) to exposé native device functionality to the browser. 

Table 1-2. Android OS Features and Browser Accessibility Matrix 



Device Feature 


OS Version Support 


Browser Access 


Connectivity detection 


> 1.5 


Bridge 


Geolocation (GPS) 


> 1.5 


Yes 


Hardware sensors 


> 1.5 


Bridge 


Touch screen and touch events 


> 1.5 


Partial 


Local storage and databases 


> 1.5 


Yes 


Messaging/notifications 


>2.2 


No 


Camera 


> 1.5 


Bridge 
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Preparing the Development Environment 

Now that you have a high-level understanding of what you can do on the Android 
platform with regard to web apps, leťs move on to getting our development 
environment set up so we can start developing applications in tine next cinapter. 

Tliere are multiple approacines tínat can be taken winen putting togetlier an effective 
development environment for mobile web apps on Android. The basic components of 
the setup outlined in this section are a text editor, a web server, and an Android 
emulátor (or handset). You couid, however, choose to use an IDE like Eclipse instead 
(see http://eclipse.org). 

Eclipse is an IDE that is tailored for Java development, and the Android team offers 
native Android development tools for Eclipse. If you are working with both web and 
native Android development, you may prefer to continue with the Eclipse environment— 
and if this is the case, there is nothing in this book that will preclude you from doing so. 



NOTE: While there are many merits to using a full-featured IDE for web development, I personally 
prefer using lightweight and separate tools. Using a standalone web server and accessing the 
content from your device's browser will allow you to more easily test multiple devices 
simultaneously without the overhead that might be imposed by using tools provided within the IDE. 

Additionally, if I decide to focus on another mobile device as a primary development target, I can 
continue to use the same tool set to develop for that platform. I anticipate that we will see two or 
three dominant players and a long trail of perhaps ten-plus platforms in the mobile space, so 
having an approach that works across devices is definitely appealing. 



Text Editors and Working Directories 

Any text editor that you are comfortable using will serve you more than adequately when 
writing web apps for Android. If you really aren't sure which text editor you want to use, 
then Wikipedia (as usual) has an excellent comparison list (see 
http : //en . wikipedia . org/wiki/Comparison_of _text_editors). 

With your trusty text editor now beside you, iťs time to set up the directory that you are 
going to work from as you progress through this book. The actual location of the 
directory is completely up to you, but I wouid recommend building a folder structure 
similar to the following, as this will assist you in working through the examples: 

■ PRODECT_WORKING_DIR 

■ css 

■ img 

■ js 

■ snippets 



Reusable CSS, image, and JavaScript resources will be stored in the css, img, and js 
folders, respectively. As we progress througli the bool<, we will build folders for each 
chapter under the snippets directory for that chapter. 

Web Server 

Having a web server serving your application code as you develop it really heips 
streamline your development process. Throughout the book we will be working primarily 
with client-side technologies, so our requirements for a web server are quite lightweight. 
This means pretty much any web server will do the job, so if you aiready have a web 
server that you wish to work with, that is absolutely fine. 

For those who don't, however, we will quickly walk through getting a lightweight web 
server called Mongoose running on Windows, Mac OS, and Linux. Mongoose is 
extremely simple to get running; just follow the installation guide for your platform as 
deschbed following (there may be some differences depending on your individual 
configuration). 

Mongoose on Windows 

Firstly, downioad the Mongoose standalone executable (mongoose- 2. 8.exe at the time of 
writing) from the project downioads page: http://code.google.eom/p/mongoose/ 
downloads/list. 

There is an installer package available, but installing Mongoose as a service won't be as 
simple as using the standalone executable. Once the file has been downioaded, put the 
executable file somewhere on your path (recommended but not required), and then skip 
to the "Running Mongoose" section of this chapter. 

Mongoose on Mac OS 

The simplest way to install Mongoose on Mac OS is by using MacPorts 
(www.macports.org). If you don't aiready have MacPorts installed, install it now by 
following the simple instructions provided on the MacPorts web site. 

With MacPorts installed, to install Mongoose run the following command: 
sudo port install mongoose 

If MacPorts is installed correctly, this shouid downioad, build, and install Mongoose, 
after which it shouid be ready for your immediate use. Proceed to the "Running 
Mongoose" section of this chapter. 

Mongoose on Linux 

With Mongoose being so lightweight, it is actually very simple to build Mongoose from 
source on most Linux systems. The following instructions are for systems running 
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Ubuntu, but oniy minor modifications will be required to adapt this to another Linux 
systém. 

Firstly, downioad the Mongoose source from wget 

http : //mongoose . googlecode . com/f iles/mongoose- 2 . 8 . tgz. 

Next uncompress the downioaded archive file: 
tar xvzf mongoose- 2. 8. tgz 

Change directory to the Mongoose source directory: 

cd mongoose 

And then run make targeting Linux: 

make linux 

You will now be able to run Mongoose using the full path of the Mongoose executable. If 
you wouid prefer to be able to run Mongoose without specifying the full path, then copy 
the Mongoose executable into a path such as /usr/local/bin: 

sudo cp mongoose /usr/local/bin/ 

Thaťs it— you can now run Mongoose. 

Running Mongoose 

Running Mongoose is refreshingly simple. Configuration defaults are sensible, so 
running mongoose from the command line produces a web server that runs and serveš 
that folder as the web root. 

Additionally, Mongoose will bind to all of the IP addresses assigned to your computer, 
which means that you will be able to browse from other devices on your network using 
the IP address (or one of the IP addresses) of the machine you are running Mongoose 
from. 

Leťs try running Mongoose now. Open up a command prompt/terminal window and 
then change directory to PR01ECT_W0RKING_DIR, which you set up in the previous step. If 
Mongoose is located on your path, you will be able to run mongoose from the command 
line; and if not, then you will need to run it using its absolute path. Either way, once you 
have run the command (no command-line options required), you shouid then be able to 
browse to http : //localhost : 8080/ and see the directory file list of the folders you set 
up earlier (as shown in Figuře 1-1). 
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Figuře 1 -1 . With Mongoose running, you shouid see a directory list of folders created earlier 



Alternativě Approaches 

You can also copy files across to an emulated SD card image and load them from the 
image by using the file://sdcard/<filelocation> syntax. If you are interested in more 
Information on Inow to create SD card images and copy files to and from tinem, I 
recommend cinecking out tlie information at tine following URL: 
http://developer.android.eom/guide/developing/tools/emulator.html#sdcard. 



Emulátor 

To test the samples, you will either need an Android handset or the Android emulátor 
that comes bundled with the SDK. If you don't aiready have the SDK, you can downioad 
it from http://developer.android.com/sdk. Follow the instructions on the Android site, 
with the exception of Installing Eclipse and the ADT plug-in (uniess you aiready have it 
installed and are comfortable using it). Once you have the Android SDK installed, the 
emulátor and associated tools can be found in the tools directory of the SDK installation 
directory. 



Creating an Android Virtual Device 

Creating an Android Virtual Device (AVD) is straiglitforward when using the GUI tools 
that are provided as part of the Android SDK. First, locate the android executable and 
run it. The location of the executable will depend on the SDK installation path, but 
essentially you are looking for thefile android (android.exe on Windows) within the 
tools folder of the SDK installation directory. This will launch the Android SDK and AVD 
Manager application, which is shown in Figura 1-2. 



Android SDK and AVD Manager 
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Figuře 1-2. The Android SDK and AVD Manager 



Here we will create a device for running our samples. Nothing too fancy is required, just 
the standard emulátor running with version 2.1 of the SDK or greater. Press the Add 
button to start creating the image. Once you have done this, you shouid see a screen 
similar to the one shown in Figuře 1-3. 



o o n Create new Ardroid Virtual Device (AVD) 



Name: 

Target: 
SD Card: 



andíoid_web_apps 



Android 2.1-updatel - API Level 7 





© Size: 50 


í MIB ; 1 




0 File: 


Browse... 



Skin: 



Hardware: 



0 Built-in: f Default (HVCA) "Tj 

OResolution: 4go x 840 



Propertv Vaíue 

Abstracled LCD density 160 



New... 



De lete 



Overríde the existing AVD with the same name 



( Create AvH~) ( Cancel ) 



Figuře 1-3. Creating a new AVD for the emulátor 

You need to provide at least three pieces of information when creating a new AVD file: 

■ The name of tlie device (no spaces are allowed). Here we are creating 
a device called "android_web_apps." TIlis is tlie name that is used 
when launching the emulátor from the command line. 

■ The target Android API we are developing for. At the time of writing, 
both Android OS versions 2.1 and 2.2 have the highest levels of 
market penetration, with 1 .5 and 1 .6 now in the minority (see 
http://developer.android.com/resources/dashboard/platform- 
versions.html). For the examples in the book, we will primarily work 
with a version 2.1 emulátor. By using a version 2.1 emulátor rather 
than a version 2.2 emulátor, we can make sure our code will work on 
both versions of the OS — but it is still important to test on as many 
versions of the OS as possible. 
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■ The size of the SD card. You can also specify an existing SD card 
image if you want to, but thaťs not required for running through the 
samples in the bool<. I'd recommend just specifying a size of SOIVIB or 
thereabouts. 

Other information, such as the skin value (somewhat synonymous with screen resolution), 
will be automatically populated based on the API version selection, but you can tweak 
these options if desired. AI! of the samples in the book have been designed with a 
standard nnobile device screen size of 320x480, so Td recommend working with that. 

) 

NOTE: Some of the examples in the book illustrate the difference between standard dpi (dots per 
inch) and high dpi, and how that will impact your applications. For these samples, you will need 
an AVD that is configured with a higher screen resolution than standard. When configuring this 
device, select a resolution such as WVGA800 (or similar) to emulate a device with a high device 
1 dpi. 



Starting the Emulátor 

Once the AVD has been created, you can then start the device by pressing the start 
button, which is displayed to the right of the device images. You will be prompted with a 
couple of options (as shown in Figuře 1-4), but in generál selecting the defaults is fine 
(aithough wiping user data can sometimes be very useful for getting back to a clean 
slate). 

n O Cl Launch Options 

Skin: HVCA (320x480) 
Density: Medium (160) 
rj Scale display to real slze 

Screen Slze (In): 3 
Monitor dpi: 7^ 
Scale: default 

Q Wipe user data 



Launch ') Cancel ^ 

Figuře 1-4. Launching a new virtual device for our emulátor using the AVD Manager 



Once the emulátor has started, a screen similar to Figuře 1-5 will be displayed, 
indicating that the Android emulátor is starting. 



5S54:android_web_apps 




Figuře 1-5. The Android emulátor starting — a good time to get some coffee 



Be aware that the emulátor does take quite a long time to load, so once youVe got it 
loaded, try to avoid closing it. When iťs finally loaded, you will see an Android home 
screen like the one shown in Figuře 1-6. 
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Figuře 1 -6. The Android emulátor has loaded successfully; open the browser to get started. 

From the home screen, run the browser and you will be able to access the local web 
server that you configured previously. 



Hello World 

Before we get into the working through the specifics of mobile web applications and 
sites in the next chapter, leťs make sure our development environment is set up 
correctly with a very simple Hello World example. 

First we will create a very simple HTML file that we will use to validate that we can view 
our development files in the mobile browser on our Android device: 

<html> 

<style type="text/css"> 
body { 
font: 4e[n Arial; 

} 

</style> 
<body> 
Hello World 
</body> 
</html> 



Save the preceding code sample to a file named helloworld.html, and then access the 
directory in which that file is stored from your terminal or command prompt. Run 
Mongoose (either using the absolute installation path or just mongoose, depending on 
how you installed it and your path configuration) from that location. 

Figuře 1-7 shows a screenshot of some example command-line output you will see if 
Mongoose has been run correctly. 
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Figuře 1 -7. Mongoose web server example output showing the port and directory that content is being served 
from. 

While Mongoose will inform you of the port it is running on, you will also need to find the 
IP address of your machine so that youYe able to browse the server from both the 
emulátor and an actual Android device connected to your local network via WiFi. One of 
the simplest ways to determine your IP address is through the use of the if conf ig or 
ipconf ig commands on Mac OS/Linux and Windows, respectively. If you are unfamiliar 
with the technique then the following links may be of assistance: 

■ PC: www.wikihow.com/Find-the-IP-Address-of-Your-PC 

■ Mac: www.wikihow.com/Find-Your-IP-Address-on-a-Mac 

■ Linux: linux-ip.net/html/tools-ifconfig.html 

Armed with the knowledge of your IP address, you will now be able to view your test 
page in the emulátor (or your Android device). Figuře 1-8 shows example screen 
captures from the Android browser, showing both browsing to the helloworld.html file 
that we created and what is displayed in the browser as a result. 



NOTE: While you may be accustomed to using localhost (or 127.0.0. 1) when browsing a 
development webserver when operating on your own machine, when you are working with an 
Android emulátor (or device) you will need to access the webserver via the IP of your machine i 
your local network. Mongoose is very helpful in this regard and will happily serve web pages 
from any IP (including 127.0.0.1) that is associated with your machine. 
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Figuře 1-8. Browsing to our Hello World example demonstrates that our development setup is working. 



Now that you have successfully created a Hello World example, it is time to move on to 
actually learning winat makes a web application or site mobile. This is the topič for the 
next chapter. 



NOTE: To keep things simple, in this example we ran Mongoose from the same directory that the 
helloworld . html file was stored in. For tlie remainder of tlie examples, we will be working in 
a siiglitly more complicated directory structure to ensure that we can reuse certain files between 
chapters. For instance, in the example source code repository on GitHub 
(http://github.com/sidelab/prowebapps-code), this file is stored in the following 
location: /snippets/oi/helloworld . html. 

This is the kind of directory structure that will be used for the rest of the book, with each 
chapter's code samples being stored within a directory underthe snippets directory. Some 
larger examples, such as the geospatial game covered in Chapters 9 through 1 1 , will use a 
variation on this structure, but this is the generál rule. 

In future examples, Mongoose will be run from the directory above snippets. This in turn 
means that the path you will use to browse the majority of future examples will match the 
following pattern: http : //YOURIP : 8080/snippets/CHAPTER/SAMPLE . html. 



Summary 

This chapter covered the basic capabilities of an Android device and what can be 
achieved in web apps as opposed to native apps. This included looking at what is 
available via standard browser support, as weil as through using bridging frameworks to 
extend native functionality to a web browser embedded in a native application. 

We also walked through the very simple requirements for running a developnnent 
environment for building Android web apps. Additionally, we took a preliminary look at 
some of the tools that will help you debug your code as you work through the samples 
in this book and later you create your own applications. 

In the next chapter, we will look at some of the simple techniques that are used to create 
mobile-friendly web pages and the foundation pieces of a mobile web app. We'll begin 
with some simple standalone examples, but quickly move on to working through a 
practical example: building a simple to-do list application. We will continue to explore 
and build this in Chapters 3 and 4 also. 




Building a Mobile HTML 
Entry Form 

Creating a simple, mobile-friendly web page is very easy. By the end of this chapter, you 
will know not oniy how to build a mobile web page and form, but understand how to 
apply some simple CSS (including some CSS3) to give a web form a very similar feel 
and experience to what you wouid find in a native application. 

The samples in this chapter and subsequent chapters work towards creating a simple 
to-do list web application optimized for Android. Building mobile web applications has a 
heavy focus on JavaScript in addition to HTML and CSS. So, in addition to 
understanding mobile web app development techniques, understanding how to 
structure JavaScript-heavy applications will be explored. 

HTML for the Mobile Web 

HTML for the mobile web is much the same as it is for the desktop— just with smaller 
screen sizes (in most cases at this stage). Additionally, there is an increased focus on 
optimizing for performance given the reduced bandwidth that a mobile device has 
access to when browsing via a mobile broadband connection. 

The focus in this chapter is on the techniques and tools required to make the jump into 
mobile web app development, primarily from an application presentation perspective. 

Moblle-Ready Web Pages 

Building mobile-ready web pages is quite simple, and onIy requires the addition of some 
extra Information to tell the mobile browser to recognize the page as "mobile ready." 
Leťs start this chapter by having a look at a simple web page. 

We will first have a look at a mobile browser without the appropriate tweaks applied. 
This will give you an understanding of why you need to optimize your web pages for 
mobile if you want people to be able to use them effectively. This is especially important 
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if you are building applications that people may compare side by side with an Android 
application that has been constructed using a native user interface (Ul). 

Our test web page is a simple page that consists of nothing more than a heading and a 
paragraph of text (lorem ipsum paragraph condensed): 

<html> 
<head> 

<title>Simple Mobile Web Page</title> 
</head> 
<body> 

<hl>Welcome</hl> 

<p>Lorem ipsum dolor sit amet ... </p> 
</body> 
</html> 

Figuře 2-1 shows how the preceding HTIVIL appears in the Android browser. 
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Figuře 2-1. Our simple web page with no mobile readiness applied 



While the browser has successfully rendered the page, there are a few things that it 
hasn't done weil: 

■ The text on the page is quite small; this is because the browser has 
assumed that it has been built for a desktop screen resolution and has 
thus applied sonne scaling to ensure the page will fit properly. 

■ Because the browser believes the page is designed for desktop 
display, it is permitting zoom and xy-axis scroll operations on the 
page. 
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■ The URL bar for the browser is displayed, and while this isn't a 
problém now, when we get into more complicated applications, it 
wouid be nice to know how we can get the Android browser to hide 
the URL bar. 

Now that you know a few things that you want your mobile browser to do (or not to do) 
when displaying the page, leťs have a look at what is required to get there. 



Introducing the viewport Meta Tag 

The HTML viewport meta tag was introduced by Apple for use in Mobile Safari on the 
iPhone, and is used to tell the mobile browser exactly what it is seeing. Without a 
viewport meta tag, the browser will assume it is looking at a web page that is built for 
desktop browsing and thus scale the display down to fit. An example viewport meta tag 
definition is as follows: 

<meta name="viewport" content="width=device-width; user-scalable=0; " /> 

In this particular instance, we are telling the browser that we wish to have the page 
displayed at the screen width of the device, and that the user shouid not be permitted to 
zoom in and out on the viewport. Zooming in and out on the display is generally pretty 
handy when looking at a site that hasn't been optimized for mobile; however, when 
viewing a mobile-ready page, iťs not generally required, and can sometimes be a 
hindrance to other functionality that you want to offer in your app. 



NOTE: While the viewport meta tag is something you wouId expect to be part of the HTML5 
specification, this is not the case at this stage However, both WebKit and Mozilla browsers are 
actively using the tag, and will be working with the W3C to have it incorporated as part of the 
specification. 



While this viewport meta tag is sufficient for telling the WebKit browser on Android how 
you wouId like the page sized, other mobile devices may require some extra Information 
to configure the display properly. To help with constructing a viewport meta tag that will 
work on the majority of mobile devices, Tve included a quick reference table. Table 2-1 
outlines the various parameters you can include in the content section of the meta tag 
and a bhef explanation of each. 
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Table 2-1. viewport Meta Tag Parameters and Their Effects 



Parameter 



Overview 



Valid Values 



Standard viewport Meta Tag Parameters 



width 



Specifies the width of the viewport. 
Tlnis can be a specific value in pixels 
(not recommended) or l<eywords tliat 
describe the required display width. 



device-width: The screen width of 
the device. 

A numerical value for the absolute 
width of the viewport. 



height 



Specifies the height of the viewport. 



device-height: The screen height of 
the device. 

A numerical value for the absolute 
height of the viewport. 



user-scalable Specifies whether the user is 

permitted to adjust the scaling of the 
screen. 



1, yes, or true: User scaling is 
permitted. 

o, no, or falše: User scaling is not 
allowed. 



initial-scale Specifies the initial scaling value for 
the display. 



A value that indicates the scaling that 
will be applied when the page is 
initially loaded. A value of i.o 
indicates that 1 viewport pixel 
equates to 1 screen pixel. 



minimum-scale Specifies the minimum scaling that 
can be applied to the display. 



A value in the range of o to lO.O. 



maximum-scale Specifies the maximum scaling that 
can be applied to the display. 

Android-Specific Meta Tag Parameters 

target- Informs the device exactly what 

densitydpi screen density the current web 

page/application was designed for. 



A value in the range of o to lO.O. 



device-dpi: Sets the viewport dpi 
density to match the dpi density of 
the device. 

high-dpi, medium-dpi, or low-dpi. 

A value in the range of 70 to 400 
specifying the specific pixel density 
of the device. 



* dpi (dots per inch) is a measure of screen pixels per incti (DPI stands for Dots Per Inch). The 
Android piatform caters for devices of varying pixel densities and broadly categorizes those into 
high, medium, and low. 



NOTE: Iťs worth reading the article "A pixel is not a pixel is not a pixel," by John Gruber, which 
explores the issue of increasing screen densities on mobile devices and the impact this will have 
for web developers as we move forward (see 

www, quirksfflode . org/blog/archives/2010/04/a_pixel_is_not . html). 



Considering these extra configuration parameters, tlie following viewport meta tag 
declaration offers the some extra robustness for cross-platform device compatibility: 

<meta name="viewport" content="width=device-width; initial-scale=l.Oj maxi[num-scale=l.O; 
user-scalable=0; " /> 

For the moment, we will not specify a target-densitydpi, but Til introduce this setting 
later when discussing the HTML5 canvas so you can understand its effect on a display. 

With the preceding viewport meta tag applied, our page will now be displayed in a more 
readable fashion; additionally, the zoom controis have been removed, as shown in 
Figuře 2-2. 
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Figuře 2-2. A simple page with the viewport meta tag applied 



Autohiding the URL Bar 

Given that the goal of this book is to provide you with the techniques required to 
successfully build a web app that will compete with a native app, having a URL bar 
visible in your app isn't going to help with convincing people. Depending on the 
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direction you take for deploying your application (remember it is possible to deploy 
mobile web apps as native applications using tools like PhoneGap^) you will be able to 
hide the URL bar automatically, or you may have to implement some workarounds to get 
it to hide effectively. 

In the oase where you are building an application that will be deployed online and 
primarily accessed through the mobile browser, a workaround is going to be required. 
Currently, the most effective workaround is to tell the browser to scroll to the top of the 
screen once it has finished loading the page. This works because the vertical scrolling 
behavior for the browser when viewing web pages is to first scroll off the URL bar, and 
then through the rest of the content. So, executing window.scrollTo(Oj l) when the 
window has finished loading will do the triek. For now, we will just add it to the body 
onload tag like so: 

<body onload="window.scrollTo(0, l);"> 

ř 

NOTE: Successfully implementing tliis teclinique requires the page lieight value to be at least as 
large as tiie display slze of tlie screen. This is generally best achieved by telling the body tag 
that it has a min-height in the stylesheets for your web app. For an example, have a look at 
the CSS implemented in the "Adding Some Style" section later in the chapter. 



Adding Form Elements 

In terms of the actual HTML code, HTML form elements are the same for mobile devices 
as they are for desktop browsers. Iťs just the interaction with those controis that 
changes for a mobile device, and thankfully Android takés care of all that for you. This is 
not that surprising given that a HTML form element is simply an instruction to the 
browser saying, "Put native control here." 

For the sake of simplicity, we will initially set a "task" in our to-do list application to have 
three properties: 

■ Name 

■ Description 

■ Due date (and time) 

We now need to create a very simple form that will allow a user to supply those details. 
The following HTML code (which is again very simple) creates such a form: 

<hl>Create Task</hl> 
<form> 
<div> 

<label for="tasl<name">Tasl< Namex/labelxbr /> 
<input type="text" name= "task [ name ] " id="taskname" /> 
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</div> 



<div> 

<label for="taskdesc">Task Description</label><br /> 
<textarea name="task[description] " rows="5"></textarea> 
</div> 

<div> 

<label ■for="taskdue">Task Due: </label><br /> 
<input type="text" name="task[due] " id="taskdue" /> 
</div> 

<input type="submit" name="Save" /> 
</form> 

Figuře 2-3 shows the preceding HTML rendered in tine browser of tlie Android simulator. 
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Figuře 2-3. Rendered output from simple HTML fora Create Task form 

As you can see in tine figuře, using vanilla HTIVIL to generate a form isn't really going to 
Inave tine appeal required to convince people to use Android web apps over a natively 
built app. We are definitely going to have to do something about this. 

Adding Some Style 

The easiest way to apply a native feel to form controis for most mobile platforms is not 
to apply any style to the control at all (very Zen sounding, isn't it?). Rather, we will tell 
the control just to leave the styling to us, and we will apply some CSS styles to some 
surrounding HTML elements. 




In this next example, we are going to need some surrounding HTML elements that will 
have CSS styles applied to improve the look and feel of the form. While we probably 
couid work with the div elements we created previously, leťs move to using an 
unordered list (ul), as this will provide us more options for further styling later on. 
Replace the form code from before with something that looks like this: 

<form id="taskentry" onsubmit="return falše; "> 
<ul> 

<li><input type="text" name="task[name] " id="taskname" placeholder="Task Name"/></li> 

<li><textarea nafne="task[description] " id="taskdesc" placeholder="Description" 
rows="5"></textarea></li> 

<li><input type="text" name="task[due] " id="taskdue" placeholder="Task Due" /></li> 

<li class="naked"><input type="submit" name="Save" /></li> 
</ul> 
</form> 

This HTML generates output that is displayed in Figuře 2-4. 
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Figuře 2-4. Updated layout using HTML5 placeholders 

In addition to restructuring the form to use a list, we have also removed the label 
elements and replaced them by using the HTML5 placeholder attribute for the input 
fields and text area. This provides a simple (and limited-screen-real-estate-friendly) 
mechanism for giving the user cues for what is required in each form field. 



r 

HTIVIL5 ALERT: You may be wondering why HTML5 is sneaking in so soon. What happened to 
writing some JavaScript and applying some CSS to aclileve that placeholder triek the way we 
used to do for desktop web applications? The reason is tliat the placeholder attribute, while 
i simple, demonstrates some of the useful features that have been added to HTIV1L5 to make a 
web developer's lite easier. ^^^^^^^^^^^^^^^^^^^^^^^^^^m 

With the placeholder attribute and tine new layout, we are Inalfway to Inaving a pretty 
nice-looking form. Leťs liave a look at some CSS tínat will get us the rest of the way 
there. Now we just need to add some CSS to style the HTML elements. This is probably 
a good time to start building our todolist.css file, which will be used by a number of 
the pages in our app. 

body { 

margin: Opx; 
min-height: 480px; 
font-family: Arial; 

} 

form ul { 

margin: Opx; 
padding: 6px; 
list-style-type: none; 

} 

form ul li { 

margin: 0 0 4px 0; 
-webkit-border-radius: 4px; 

border: ipx solid #666665; 
padding: 4px; 

} 

form ul li.naked { 

-webkit-border-radius: Opx; 

border: 0; 
padding: 0; 

} 

input, textarea { 

-webkit-appearance: none; 

border: 0; 
width: 99%; 

} 

input[type=submit] { 

border: ipx solid white; 

background: -webkit-gradient(linear, left top, left bottom, color-stop(0.0, 
#F8F8F8), color-stop(l.O, #AAAAAA)); 
-webkit-border-radius: 6px; 
-webkit-box-shadow: O O 4px #333333; 

width: 100%; 
padding: 6px; 

} 
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This stylesheet can now be included in your form code, with the following HTML tag 
placed in tine head section of tine page: 

<linl< rel="stylesheet" media="screen" href="todolist.css" /> 

Notice tínat some nonstandard CSS definitions that liave been included in tlie code 
(shown in bold in the preceding code snippet). I will discuss tliese in more detail in the 
following section. 



NOTE: Tliese kinds of CSS definitions will be used throughout the book. They represent early 
WebKit implementations of CSS3 (the next generation of CSS) that are often used in conjunction 
with HTIVÍL5 to achieve some nice visual effects. HTML5 and CSS3 are very complementary 
technologies, and their combined use is really the enabler tor mobile web apps to compete with 
native mobile apps. 



Figuře 2-5 shows the browser output displayed after the preceding CSS is applied to 
our adjusted HTIVIL. 
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Figuře 2-5. The updated form layout with CSS applied 



Form Styles with a Splash of CSS3 

About 75 percent of the preceding CSS is a mix of CSS1 and CSS2, which has been 
around now for some time. However, there is also a smattering of CSS3, and most of 
this is quite new. This stylesheet includes some WebKit-specific CSS3 definitions that 
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enable us to make our form look very nice without requiring the use of external image 
resources. 

NOTE: The CSS3 specification (like the HTML5 specification) is not yet finalized. For this reason, 
the CSS3 definitions here are implemented using the proprietary -webkit prefix (for the WebKit 
browser family, other browsers will implement their own proprietary prefix). This indicates that 
the folks at WebKit are confident that these sections of the CSS3 spec will make the finál cut. 
Once the CSS3 specification is locked down, then the -webkit prefix will be dropped and 
replaced by the standard name. 

As an example, -webkit-box-shadow will simply become box-shadow. This is definitely 
worth keeping in mind when building your mobile application — especially given thatthere is 
nothing stopping someone from installing a different mobile browser on their Android device. If 
you want your web app to display in browsers other than WebKit, try to use proprietary CSS3 
extensions for eye candy oniy. Either that or include definitions for the other browser-rendering 
, engines that you want to support in the style definitions also. 

Leťs have a brief look through the CSS3 extensions used in this example (more detail is 
provided in the Appendix of the book). 



appearance (-webkit-appearance) 

This CSS3 property is used to tell the browser what type of native of control we wouid 
like to be displayed. There are many different control types that can be specified. For 
this example and many other instances, it is simplest just to set the appearance to none 
and to apply the look and feel through surrounding elements. 



border-radius (-webkit-border-radius) 

The border-radius property provides a very simple and nice way of applying a border to 
your HTML elements. In addition to being able to specify the corner rádius for all corners 
of your element with this property, you can specify specific and different radii for each 
individual corner using the following properties: 

■ border-bottom-left-radius 

■ border-bottom-right-radius 

■ border-top-left-radius 

■ border-top-right-radius 

A rádius property will take either one parameter that specifies the overall corner rádius, 
or two parameters, specifying the horizontál rádius and vertical rádius for the corner(s), 
respectively. 



box-shadow (-webkit-box-shadow) 

The box-shadow property is used to apply a shadow to HTML elements without requiring 
external image resources— very nice. The property takés four parameters that allow you 
to specify how the shadow shouid appear: 

■ Horizontál offset This defines where the shadow shouid be positioned 
relative to the control in the horizontál direction. Positive values 
position the shadow to the right of the control, and negative values 
position it to the left. 

■ Vertical offset This works like the horizontál offset, but on the vertical 
axis. Positive values position the shadow below, and negative values 
position It above. 

■ Blur rádius: This specifies the rádius for the blur effect. Basically, 
bigger numbers mean a larger shadow that fades out gradually; 
smaller numbers mean a smaller, crisper shadow. 

■ Sliadow color. This specifies the color of the shadow— pretty self 
explanatory, really. Most commoniy, you'll be using shades of gray 
here, but colors can be used to create glow effects. 

gradient fill style (-webkit-gradient) 

So far, weVe used shadows and rounded corners in our form; now we'll take a look at 
using gradients, which can help capture the visual appeal of many current mobile apps. 
Gradients in CSS3 are not implemented as a CSS3 property, but rather as a fill style— 
and they are very powerful and quite configurable. Tm sure there are whole chapters 
dedicated to gradients in a CSS3 book, so I won't attempt to cover all the detail here. 
Essentially, there are two types of gradients: linear and radiál. This chapter's example 
uses a linear gradient, so Til cover that here. Specifying a linear gradient requires a 
minimum of five parameters (to actually make a gradient effect occur), but more can be 
used to specify additional color stops. 

■ Gradient type: This is the type of gradient you are going to display— 
linear or radiál. 

■ Point 1: This is the starting point of the gradient. Iťs a pair of space- 
separated values that specifies the position. We used names in our 
example (left top and left bottom), but additionally numeric values (in 
the range of 0.0 to 1 .0) or percentages can be used. 

■ Point 2: This is the ending point of the gradient. 
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■ Stop 1: This is the starting color stop. Defining a color stop is done 
using the color-stop function. The function takés two arguments. The 
first specifies the relative position between point 1 and point 2 at 
which the color is used. You can use numbers or percentages to 
define the position. If using nunnbers, o.o equates to "at point 1" and 
1.0 equates to "at point 2." Using percentages, o.o is equivalent to O 
percent and l.o is equivalent to 100 percent. The second argument is 
used to define the color that will be used at the specified position. 

■ Stop 2: This is the next color stop. To create a gradient effect, oniy 
two stops are required, but more can be specified. 

This shouid start to make more sense when you look at the example in the preceding 
code sample. If it doesn't, however, then Td suggest that you just flip to the reference 
section and have a look at some gradient samples. 

Improving the Page Title Appearance 

Now that the form is looking a little more presentable, that run-of-the-mill hl tag for a 
title is looking a little out of pláce. Leťs see what we can do to improve the presentation. 
We'll have a look at a couple of options. First, we'll apply a vanilla styling that looks 
similar to what you might see as a subsection title in a native Android app. Second, we'll 
use some of the CSS3 styles that we played with previously to dress it up a bit. 

The two different CSS classes we are going to experiment with follow— just add them to 
the end of the todolist . css stylesheet, and depending on the look you wouid like for 
the application, apply one and delete the other. 

hl.simple { 

font-size: 0.9em; 
padding: 4pxj 
background: #333333; 
color: #AAAAAA; 

border-bottom: 2px solid #AAAAAA; 
margin: O O 4px Oj 

} 

hl.fancy { 

background: -webkit-gradient(linear, left top, left bottom, color-stop(0.0, 
#666666), color-stop(0.5, #3A3A3A), color-stop(0.5, #222222), color-stop(l.O, #000000)); 
-webkit-box-shadow: O 2px ipx #AAAAAA; 
-webkit-border-bottom-left-radius: 6px; 
-webkit-border-bottom-right-radius : 6px; 
font-size: l.lem; 
color: white; 
padding: lOpx 8px; 
margin: O 6px 6px 6px; 
text-align: center; 

} 

Once these styles are applied to the hl tag (by setting the class attribute of the tag), 
you'll get the results displayed in Figuře 2-6. 
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Figuře 2-6. Two header styles compared 



Coding for Different Screen Sizes 

Devices powered by the Android OS can come with in a variety of screen sizes, winicin 
means that we really want to build our forms and apps to be able to adjust their 
appearance to make the best use of tine available screen real estate. In most cases, this 
is done best by using relative dimension specifications (i.e., percentages) ratherthan 
specific, absolute values (i.e., pixels). 

While this might be enough to ensure that a form looks presentable for all screen sizes, 
it certainiy won't guarantee that iťs going to look good. For these situations, we need to 
provide customized stylesheets for the varying device sizes. This is surprisingly simple, 
and can be done by specifying the appropriate device widths in the media attribute of 
the link tag. For instance, the following code wouid include the stylesheet 
smallscreen.css for devices with a width of 480 pixels and the stylesheet 
largescreen.css for larger screen sizes. 

<link media="only screen and (max-device-width: 480px)" href="smallscreen.css" type= 
"text/css" rel="stylesheet" /> 

<link media="only screen and (min-device-width: 48lpx)" href="largescreen.css" type= 
"text/css" rel="stylesheet" /> 




TIP: I would recommend using three stylesheets (instead of two, as just shown) when it comes I 
to writing anything more than a simple app. If you can effectively separate your CSS styles into 
those that apply regardless of screen size and those that are dependent on screen size, you will 
have an easier time managing your code in the long run. 

Using tiiis approachi, the preceding example would have a core stylesheet (say, 
allscreens.css) that is brought into the HTIVIL document without the device width rules in the 
I linl< tag. All CSS that is not dependent on screen size would be moved to this tile, and the 
l smallscreen . css and largescreen . css files would oniy contain the size-specific rules. 

Handling Device Orientation Changes 

In addition to Inandling differing screen sizes, our apps will likely have to respond to tine 
user cinanging the orientation of the device. Up until now, we have been designing for 
our applications being used in portrait mode. While the form we have bulit wiil piay 
niceiy in iandscape mode (as demonstrated in Figuře 2-7), it is important to l<;now when 
the orientation changes, as particuiar applications you write might need some speciai 
treatment. 
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Figuře 2-7. Using relativa position mal<es working with different oríentations simple. 

To demonstrate the techniques for dealing with screen orientation changes, leťs create 
a simple page that will provide some feedbacl< as to when orientation changes are 
occurring. 

We wili now \ook at some exampie code that impiements an orientation detection 
routine that works on both current and previous versions of Android. Additionally, we'll 
bring in jQuery here so we can do things a iittie more conciseiy. If you aren't aiready 
familiar with jQuery, it is probably worth quickly running through a jQuery tutoriál (an 
extensive list of tutorials can be found at http://docs . jquery . com/Tutorials), or else 
the JavaScript that is used in this exercise will appear a little confusing. 
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First is the page HTML: 

<html> 
<head> 

<title>Orientation Checker</title> 

<meta name="viewport" content="width=device-width; initial-scale=l.O; maximum- 

scale=l.O; user-scalable=0; " /> 

<link rel="stylesheet" media="screen" href="orientation-monitor.css" /> 
<script type="text/javascript" src=". ./. ./js/jquery-l.4.2.min. js"></script> 
<script type="text/javascript" src="orientation-nionitor . js"></script> 

</head> 

<body> 

<hl class="siniple">Orientation Monitor</hl> 

<ul class="details"> 

<li class="header">Event Details</li> 
<li><label>Type:</label><span id="event-type" /></li> 
<li class="header">Window Details</li> 
<li><label>Width:</label><span id="window-width" /></li> 
<li><label>Height:</label><span id="window-height" /></li> 
<li><label>Orientation: </label><span id="window-orientation" /></li> 
<li class="header">Detection Results</li> 
<li><label>Orientation:</label><span id="orientation" /></li> 
<li><label>Rotation Classx/labelxspan id="rotation-class" /></li> 

</ul> 
</body> 
</htrtil> 



NOTE: I haven't included the CSS here for this example, as it isn't the point of the exercise. You 
can, however, review the full source at the following URL: l 

http : / /sidelab . com/ code/pawa/ snippets/ 02 /orient ation-monitor . css 



Next is the content of the orientation-monitor. js file: 

$(docu[nent) .ready(function() { 

var canDetect = "onorientationchange" in window; 

var orientationTimer = 0; 

var ROTATION_CLASSES = { 
"O": "none", 
"90": "right", 
"-90": "left", 
"180": "flipped" 

}; 

$(window) .bind(canDetect ? "orientationchange" : "resize", function(evt) { 
clearTimeout(orientationTimer) ; 
orientationTimer = setTimeout(f unction() { 

// display the event type and window details 
$( "#event-type" ) . html (evt .type) ; 
$("#window-orientation") .html(window.orientation); 
$("#window-width" ) . html (window. innerWidth) ; 
$("#window-height" ) . html (window. innerHeight) ; 

// given we can only really rely on width and height at this stage. 



// calculate the orientation based on aspect ratio 

var aspectRatio = 1; 

if (window.innerHeight !== O) { 

aspectRatio = window.innerUidth / window.innerHeight; 
} // if 

// determine the orientation based on aspect ratio 

var orientation = aspectRatio <= 1 ? "portrait" : "landscape"; 

// if the event type is an orientation change event, we can rely on 

// the orientation angle 

var rotationText = null; 

if (evt.type == "orientationchange") { 

rotationText = ROTATION_CLASSES[window. orientation. toString()]; 
} // if 

// display the details we have determined from the display 
$("#orientation" ) . html (orientation ) ; 
$("#rotation-class") .html (rotationText); 
}, 500); 



}); 
}); 

Once you have implemented the code, a simulator or device will display a screen similar 
to what is shown in Figuře 2-8. 
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Figuře 2-8. The orientation monitor displaying information fora landscape orientation. 



Leťs take a walkthrough of the meaningful parts of the preceding code. Firstly, we make 
a determination as to whether the version of WebKit that the Android device we are 
using supports the orientationchange event: 

var canDetect = "onorientationchange" in window; 

Then we use the jQuery bind nnethod to attach ourselves to the relevant event— based 
on the previous detection. Here I use the ternary (or elvis) operátor to save sonne 
keystrokes. (I apologize if you aren't a fan of Elvis, but I am, so expect to see more of 
him.) 




$(window).bind(canDetect ? "orientationchange" : "resize", function(evt) { 

});" 

Next, we'll do something pretty subtie, but very important. As orientationchange and 
resize events can occur quite rapidly, we need to wait until things have settled down 
before actually attempting to handle the event. In this case, I am using the JavaScript 
setTimeout and clearTimeout functions to clear and reset a timer that will run once the 
event queue has stabilized. 

var orientationTimer = 0; 
clearTimeout (orientationTittier); 
orientationTimer = setTimeout(f unction() { 

});" 

This wraps up the preparatory work that is required to properly capture appropriate 
events for detecting orientation changes. Leťs now have a look at what is required to 
interpret the Information we are receiving. 

First, leťs work out the screen aspect ratio, and from there determine whether the 
screen is being displayed in portrait or landscape mode: 

var aspectRatio = l; 

it (window.innerHeight U= O) { 

aspectRatio = window.innerWidth / window.innerHeight; 
} // if 

// determine the orientation based on aspect ratio 

var orientation = aspectRatio <= 1 ? "portrait" : "landscape"; 

As I mention in the comments in the full code sample, the preceding code is really the 
oniy reliable way at the moment to write detection code that is going to work for most 
devices. In my testing, an Android device that did not support the orientationchange 
event still reported results for the window. orientation value, but aiways returned O, 
regardless of the device's actual orientation. 

Based on the aspect ratio of the display, we can infer the orientation of the screen. We 

can go a little further with the next section of code to get a value-add for those devices 
that do actually provide us accurate orientation Information: 

var ROTATION_CLASSES = { 
"O": "none", 
"90": "right", 
"-90": "left", 
"180": "flipped" 

}; 

var rotationText = null; 

if (evt.type == "orientationchange") { 

rotationText = ROTATION_CLASSES[window. orientation. toString()]; 
} // if 

In this code, we first look to see if the event was an orientationchange event. If so, then 
we take the window. orientation integer value, convert it to a string, and then map It to 
an array value that we will use in conjunction with CSS classes at a later stage. 



NOTE: As a platform, Android is continuing to evolve and the particular code may have differing 
effects on different versions of the Android OS. One of the common criticisms of the Android 
platform relates to the fragmented OS versions available across devices. i 

To that end, the preceding code worked for Android 1 .6, 2.1 , and 2.2 in the emulátor, but failed 
to behave correctly on an Android 2.1 device. This is something that is going to prove challenging 
for Android developers (including web app developers) until Google works with the device 
manufacturers to ensure Android OS releases are distributed to consumers. 

Until that time, it is very important to perform thorough device testing with your apps and be 
aware of any limitations that particular OS versions may have. 



What this code produces for us is essentially two string values that we can utillze for 
effectively applying stylesheets (or individual styles) for our mobile web apps. 

Once we have done this, iťs a very simple matter to tweak the code so that we can use 
it in future exercises. Essentially, we need to remove the feedback elements from the 
code (where jQuery is being used to update spans for our example app), and use the 
jQuery trigger function to fire a new event: 

$(window) .trigger("reorient" j [orientation, rotationText]); 

Once this is done, you shouid be able to tweak your code to update the detected 
orientation display elements by using jQuery bind to handle "reorient" events. If you run 
into trouble, just have a look at the finál exercise JavaScript code on GitHub: 

http://sidelab.com/code/pawa/snippets/02/orientation-nionitor.js 

BUILDING A TOOL SET: We are starting to build up our tool set of reusable code that will be 
used in later examples. While I won't cover the detail of how this is being done, you can have a 
look at the library at any time. Like the exercise code, the library is available for review at the 
URL: HHI^H^HH^HHBHBHMií^Hii 

http : / /sidelab . com/ code/pawa/ j s / prowebapps . j s 




Adding Form Validation 

Now that we have the form looking presentable, we need to add some form validation to 
make sure we are getting accurate data so that we can actually start saving new tasks in 
the next chapter. 

We will continue using jQuery from this point forward, which will give us access to some 
excellent validation plug-ins that will save us from having to write validation routines 
from the ground up. Before we get to integrating that validation plug-in, however, leťs 




consider how we are going to provide validation feedback in our application, as that is 
something we are not going to be able to just use as is. 

I l<now iťs been mentioned before, but we need to again consider limited screen real 
estate. Additionally, if you liave come from a desktop web application background, you 
will also have to come to terms with not having hover tips and associated mouseover- 
type functionality in your mobile web apps. 

So we need an effective way of communicating validation errors that doesn't take up 
excessive screen space, but provides the user enough detail to fix the problems with the 
data they have entered. 

We will explore one option for providing that feedback by looking at an example. 

Providing Feedback with Limited Screen Space 

The approach we are going to take in this application is to first indicate any field that has 
a problém with the data that has been provided with a visual cue that something is 
awry— nothing new here. While a common practice for web applications wouid also be 
to provide an overall summary of the validation errors that have been encountered for 
the entire form, we will not be able to incorporate this given the limited screen real- 
estate. As an alternativě, leťs look at ways that we can leverage the power of jQuery to 
alter the page at runtime and display those errors when a user enters a particular field. 

Given that we haven't actually hooked up the jQuery validation plug-in yet, we'll just use 
mock JavaScript to simulate some failed tests to check that our display behaves in the 
desired fashion. 

First, leťs add some basic style Information to the todolist.css file for invalid fields: 

input. invalid, textarea. invalid { 

background: url(exclamation.png) no-repeat 2px 2px; 
padding-left: 22px; 

} 

#errors { 

margin: 8px 6px 2px 6px; 
padding: 6px I4px; 

background: -webkit-gradient(linear, left top, left bottom, color-stop(0.0, 
ttccOOOO), color-stop(0.7, #770022)); 
-webkit-border-radius: 4px; 
color: white; 
display: none; 

} 



NOTE: rve included an external image resource to draw attention to the invalid field. Ttiis is 
definitely one way to do tiiings, and is great tor wliat we are doing currently. Later in thie bool< I 
wiil discuss liow you can actually embed image data directly into your stylesheets to reduce tiie 
number of HTTP requests required by your app. mHHHHBM^HBíHHHBBHBH 



Oh, and you may notice that l've used another gradient. It might be time to start admitting I have 
a problém with gradient addiction. 



Witin a way to see tínat a field is invalid, leťs implement some code to trigger the display 
of validation errors: 

var errors = {}; 

function displayErrorsO { 
// initialize variables 
var haveErrors = falše; 

// remove the invalid class for all inputs 
$( " : input . invalid" ) . removeClass ( " invalid" ) ; 

// iterate through the fields specified in the errors array 
for (var fieldName in errors) { 
haveErrors = true; 

$("input[name= ' " + fieldName + " ' ] ") .addClass("invalid"); 
} // for 

// if we have errors, then add a message to the errors div 
$("#errors") 

.html(haveErrors ? "Errors were found." : "") 

.css("display", haveErrors ? "blocl<" : "none"); 
} // displayErrors 

$(document) .ready(f unctionO { 
$("#tasl<entry") .bind("submit", function() { 
errors = { 

"tasl<[name] " : ["Tasl< name is required"], 
"tasl<[due] " : ["Due date is invalid"] 

}; // 



displayErrorsO; 
return falše; 



}); 
}); 

This code is tlie start of our todolist. js file, which we will build up to contain tine 
application logic for our web app. Rigint now, there isn't mucin to it, but by the end of 
Chapter 4, this will be quite a substantial amount of code. For now, the code simply 
binds to the submit event of the tasl<; entry form and provides the skeleton of a 
displayErrors function. If you click the Submit button on the web form, you shouid now 
see something similar to Figuře 2-9. 
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Figuře 2-9. The Create Task form simulating an error condition 



Leťs move on to providing the user additional information when they focus back on a 
field in the form. If you play around in the emulátor or on an actual Android device, you 
may notice that the screen positioning of elements when the onscreen l<eyboard is 
displayed is going to mal<e it difficult to choose a suitable location to provide the 
additional validation feedback. If you haven't yet experienced this firsthand, then just 
take a moment to throw a few extra dummy input fields in the Create Task form and 
experiment with the interface. 

Figuře 2-10 highiights the dramatic reduction of available screen real estate when the 
keyboard is displayed. 
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Figuře 2-1 0. When the onscreen keyboard is displayed, the available display height is roughiy halved. 



From my own investigations and experience, I have found that using the screen real 
estate above a control is a little more reliable than below (given that scrolling is limited 
by the height of the current HTML document). To provide the detailed feedback, leťs 
add some additional JavaScript to our todolist. js file. We'll start with adding an 
additional function that will be used to display any errors for a form element that is 
passed to it: 

function displayFieldErrors(f ield) { 
var messages = errors [f ield. name]j 
if (messages && (messages. length > O)) { 

// find an existing error detail section for the field 
var errorDetail = $("#errordetail_" + field. id). get(o); 

// if it doesn't exist, then create it 
if (! errorDetail) { 

$(field) .before("<ul class='errors-inline' id= ' errordetail_" + field. id + 

"'></ul>"); 

errorDetail = $("#errordetail_" + field. id). get(o); 
} // if 

// add the various error messages to the div 
for (var ii = 0; ii < messages. length j ii++) { 

$(errorDetail).html(' ').append("<li>" + messages[ii] + "</li>"); 
} // for 
} // if 
} // displayFieldErrors 

This code is then triggered by attaching to the focus handler of the control— the 
following code demonstrates how to do that when the document is loaded: 




$(document) .ready(function() { 

$(" :input") .focus(function(evt) { 

display FieldErrors(this); 
}).blur(function(evt) { 

$("#errordetail_" + this.id) .removeO j 

}); 
});"' 

Now we just need add an additional style definition so the iniine errors are displayed 
differently from other ul elements: 

ul.errors-inline li { 
border: Opx; 
color: red; 
padding: Opxj 

} 

Once that has been implemented, errors shouid display above an input fleid when it 
receives focus, as per Figuře 2-1 1 . 
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Figuře 2-1 1 . Detailed error messages are now displayed above an entry field when it receives focus. 

Thaťs pretty much it in terms of providing error feedback; from here all that is required is 
to include the jQuery validation plug-in and let it do the hard work of validating data. 

Setting up the jQuery validation plug-in requires the following steps: 

1. Importing the jquery.validate. js library into our HTML code 

2. Adding some validation Information to the class declarations of input fields that 
we want to validate 




3. Calling a customized version of the validate method for our form to override the 
default jQuery validation plug-in behavior to what we created previously 



Leťs start with the tweaks to the HTML: 

<html> 
<head> 

<title>Simple Mobile Web Page</title> 

<meta name="viewport" content="width=device-width; initial-scale=l.O; maximum- 

scale=l.O; user-scalable=0; " /> 

<link rel="stylesheet" media="screen" href="todolist.css" /> 
<script type="text/javascript" src=". ./. ./js/jquery-l.4.2.[nin. js"></script> 
<script type="text/javascript" src=" . ./. . /js/jquery. validate. js"></script> 
<script type="text/javascript" src=". ./. ./js/prowebapps. js"></script> 
<script type="text/javascript" src="todolist. js"></script> 

</head> 

<body> 

<hl class="fancy">Create Tasl«/hl> 
<div id="errors"></div> 
<form id="taskentry"> 
<ul> 

<li><input type="text" class="required" name="task[name] " id="taskname" 
placeholder="Task Name"/></li> 
<li> 

<textarea name="task[description] " id="taskdesc" placeholder="Description" 
rows="5"></textarea> 
</li> 

<li><input type="text" class="required date" name="task[due] " id="taskdue" 
placeholder="Task Due" /></li> 

<li class="naked"><input type="submit" name="Save" /></li> 
</ul> 
</form> 
</body> 
</html> 

That takés care of steps 1 and 2; now we just need to replace the mock validation code 
(the jQuery bind for the submit and the associated callback) with the following code: 

$("#taskentry") .validate({ 

submitHandler : function(form) { 

// TO BE COMPLETED IN THE NEXT CHAPTER 

}, 

showErrors: function(errorMap, errorList) { 
// initialize an empty errors map 
errors = {}; 

// iterate through the jQuery validation error map, and convert to something we 

can use 

for (var elementName in errorMap) { 
if (! errors[elertientName] ) { 
errors [elementName] = []; 
} II if 

errors [elementName] . push (errorMap [elementName] ) ; 
} // for 

// now display the errors 
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displayErrorsO; 

} 

}); 

Once this is done, the application shouid behave exactly as before, but rather than 
displaying our mock errors it will display error messages that have been produced from 
the jOuery .validate plug-in. 



Summary 

This chapter shouid have familiarized you with the basic requirements of building a 
mobile web app. It included a look at the viewport meta tag, and explored some of the 
CSS3 styles that can be used in Androiďs WebKit browser to create a clean user 
interface. It also covered some of the extra things to be considered when creating web 
apps for mobile devices, including device orientation changes and the extra constraints 
applied when designing an app given limited screen real estate. Finally, we made use 
the jQuery validate plug-in to bring robust forms validation into our application without 
having to whte it from the ground up. 

In the next chapter, we will look at saving our data using the various client-side storage 
mechanisms that are provided as part of HTML5. This will involve starting to get a bit 
more serious with our code, and as a result. Til be moving to using the JavaScript 
module pattern in the code samples. Employing the module pattern will provide us the 
solid foundation required to build more complicated applications in JavaScript, so while 
it takés a bit of getting used to, iťs weil with the effort. 




HTML5 Storage APls 



In the last chapter, we looked at creating a simple mobile web page and a simple Create 
Task form for our to-do list application. In this chapter, we will look at options for being 
able to store data locally on the device. HTML5 introduces a couple of APls that permit 
this kind of client-side storage. 

Previously when writing a web app, if you needed to save data to a database, you wouid 
need to use a server-side script (PHP, Python, Ruby, etc.) to do this for you. Some 
emerging elements of the HTML5 API offer a client-side alternativě for this, and 
investigating these and how to effectively use them will be the primary focus of this 
chapter. 

Essentially, three different types of client-side storage mechanisms are being 
implemented as part of the HTML5 specification: 

■ Web storage: Often referred to as HTML5 local storage, this is a client- 
side mechanism for storing key/value pairs. Iťs simple, but very 
powerful (see http://w3.org/TR/webst0rage/). 

■ Web SQL database: This provides access to a SQLite-like database, 
which is a client-side alternativě to a traditional RDBMS that you might 
find on a server (see http://w3.0rg/TR/webdatabase/). 

■ Indexed database: A draft specification that has been proposed by the 
W3C to replace the currently implemented Web SQL database 
specification, geared towards providing a "database of records 
holding simple values and hierarchical objects" (see 

http : //w3 . org/TR/IndexedDB/). 

In this chapter, we will be focusing on the first two storage APls listed above, providing 
both an overview and sample code for both. 

AIthough the Indexed DB API has been put forward by the W3C to replace the Web SQL 
database, currently no versions of Android have shipped with support for the 
specification. For this reason, we have focused on the two that you can implement and 
use right now— Web Storage and Web SQL database. 
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It is our firm belief that WebKit browsers (as used natively on Android) will continue to 
support the Web SQL database for some time to come so you shouid feel comfortable 
using that specification even though the W3C have indicated that they will not be 
creating any further revisions to the standard. 

The Web Storage API 

Both the localStorage and sessionStorage objects implement the Storage interface, 
and this provides the following methods: 

■ getitem 

■ setitem 

■ removeltem 

■ clear 

These four methods capture pretty much the entire functionality of the Storage API, and 
while they appear simple, they open up some great opportunities. The magie lies in the 
fact that you can save any object Into Storage. You just provide a key to access the 
value later, and away you go. 

In a simple oase, you might simply save a string or other simple type values into storage. 
Consider the following code: 

localStorage. setItem("preferences-bgcolor", "#333333"); 
localStorage. setltem("preferences- textcolor", "#FFFFFF"); 

This creates two values in localStorage for tracking application preferences for a 
background and text color. You couid, however, achieve the same result by just storing 
a single object in localStorage with the following code: 

localStorage. setltem("preferences", { 
bgcolor: "#333333", 
textcolor: "#FFFFFF" 

}); 

You can retrieve your preferences object by using a simple call to getitem: 
var preferences = localStorage. getltem("preferences"); 

You shouid then be able to access the background color and text color preferences 
from the preferences object. Leťs try that now. Just show an alert to display the 
background color: 

alert (preferences . bgcolor) ; 

Um, weil, thaťs embarrassing. Depending on the implementation of the Web Storage 
API browsers are using at the time you are reading this book, you may weil find that the 
preceding call just shows you a message as per the JavaScript alert displayed in Figuře 
3-1. 
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undefined 




Figuře 3-1 . Accessing objects in localStorage may notyield the expected/documented results. 

What does that mean for you right now? Can you oniy store simple values in 
localStorage and sessionStorage? Yes . . . but you can aiways use JSON (JavaScript 
Object Notation) to serialize your objects first and tlien save them as strings. This is 
definitely wortli investigating, so tlie first exercise of tinis cinapter relates to tínat. 

f 

NOTE: If you haven't encountered a situation like tliis previously, tlien weicome to tlie worid of 
i the early technology adopter — things change. We discussed this earlier, but here is a firsthand 
' example in which the browser builders believed part of the HTIVIL5 spec had stabilized enough 
for implementation, when in actual fact there were still some tweaks on the way. This is all part 
of the fun, and we are likely to come across more examples of this through the course of the 
book. 

If you do come across something that doesn't work as expected, or something in the book isn't in 
line with the current HTIVIL5 spec, then please provide some feedback online: 
www.apress.com. 
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Saving Objects to Web Storage Using JSON 

We will now investigate saving JavaScript objects to Web Storage using JSON. JSON 
provides an elegant and efficient metinod of storing JavaScript object data as a plain text 
string. Once in string fornnat, the data can then be sent to external services or saved as 



per the samples here. Before you begin saving objects in JSON formát, however, you 
are going to need Douglas Crockforďs json2. js library for serializing/deserializing 
objects to JSON strings. This library is available at the following location: 
http://json.org/json2.js. 

You can downioad tínat file into your top-level js directory so you can use it for other 
exercises later on. 



NOTE: Doug Crocl<forcl lias included an alert in the first line of the json2. js file to discourage 
people from using the library via a direct linkto his site. You will need to remove this line before 
running code samples from the exercise. If you forget, though, everything will work; you'll just 
have to click through an annoying alert each time you run an exercise using JSON. We're fairiy 
confident that by the end of the book that first line will be removed. 

Leťs create a simple page that will set up the environment for us to run our tests: 

<html> 
<head> 

<title>Web Storage Tester</title> 

<meta name="viewport" content="width=device-width; initial-scale=l.O; maximum- 

scale=l.O; user-scalable=0; " /> 

<link rel="stylesheet" media="screen" href=" . ./. ./css/snippets.css" /> 
<script type="text/javascript" src=" . ./. . /js/jquery-l.4.2.[nin. js"></script> 
<script type="text/javascript" src=" . ./. ./js/json2. js"></script> 
<script type="text/javascript" src=" . ./. ./js/prowebapps. js"></script> 
<script type="text/javascript" src="webstorage-test. js"></script> 

</head> 

<body> 

<hl class="fancy">Web Storage DSON Wrapper</hl> 
<ul id="items"> 

<li class="header">Ite[ns in Storage (tap to reniove)</li> 
</ul> 

<ul id="newite[n"> 

<li class="header">New Ite[n</li> 

<li class="bordered"><input type="text" id="newtitle" placeholder="Title" 

/></li> 
</ul> 

<ul id="actions"> 

<li><button id="add">Add</button></li> 
<li><button id="clear">Clear</button></li> 
</ul> 
</body> 
<html> 

In the preceding code, there are four generál items to take note of: 

■ Inclusion of the generic snippets stylesheet (css/snippets.css). As 
outlined in Chapter 1 , this stylesheet forms part of the reusable code 
components that we will use and expand on over the course of the 
book. Full source of the stylesheet is viewable at the following URL: 
http://sidelab.com/code/pawa/css/snippets.css. 



■ Inclusion of json2. js so we can access JSON serialization and 
parsing. 

■ Inclusion of the prowebapps. js library. We will add some handy 
wrappers for saving to localStorage/sessionStorage, which will provide 
automatic serialization/deserialization of objects using JSON. 

■ Inclusion of webstorage-test. js, winicin will include the JavaScript 
code for this exercise. 

Leťs get on with coding. First, we'll add those storage wrapper functions to tine 
prowebapps. js library. TInis is done by adding a Storage submodule to our existing 
PROWEBAPPS module: 

var module = { 

Storage: (function() { 

function getStorageScope(scope) { 

if (scope && (scope == "session")) { 

return sessionStorage; 
} // if 

return localStorage; 
} // getStorageTarget 

return { 

get: f unction(key, scope) { 
// get the storage target 

var value = getStorageScope(scope).getItem(key); 

// if the value looks like serialized DSON, parse it 

return (/'^(\{ | \[) .*(\} | \] )$/) .test(value) ? ]SON.parse(value) : value; 

}, 

set: f unction(key, value, scope) { 

// if the value is an object, then stringify using DSON 

var serializable = jOuery.isArray(value) | | jOuery.isPlainObject(value); 

var storeValue = serializable ? DSON. stringify(value) : value; 



II saMe the value 

getStorageScope(scope) .setlteín(keyj storeValue); 



remove: function (key, scope) { 

getStorageScope(scope) .removeltem(key); 

} 

}; 

})() 



While we won't go into a detailed explanation of the preceding code, those of you who 
are interested will be able to see that we wrap the getitem and setitem methods of the 
HTML5 Storage interface into get and set static methods on the PROWEBAPPS. Storage 
module. We use some jQuery utility functions and regular expressions to determine if we 
need to use JSON to store/retrieve the data, and if so, then we do. 



More important than how the preceding code works (which is relatively simple once you 
break it down) is how we will be able to use it. Basically, we now have three functions 
that permit more complex value storage at our disposal for interacting with the HTML5 
Web Storage functionality: 

■ PROWEBAPPS. Storage. get(key, scope) 

■ key is a string value used to identity the entry. 

■ scope can be optionally specified as "session" (i.e., as a string) if 
you want to store to session storage instead of local storage. 

■ PROWEBAPPS. Storage. set (key, value, scope) 

■ As per the get method, the key is a string value to identity the 
entry. 

■ value is the data that we wish to save to Web Storage. (This can 
be a simple value, array, object, etc). Arrays and objects are 
serialized using JSON and then stored as strings. 

■ scope (optional) specifies whether the key value will be saved to 
session or local storage. Passing no value to this parameter 
means that the value will be saved to local storage. 

■ PROWEBAPPS. Storage. remove(key, scope) 

■ key is a string value used to specify the entry that will be 
removed from storage. 

■ The scope parameter (if supplied) will specify whether session or 
local storage shouid be used. If no value is supplied, then 
local storage is used by default. 

Now that we have this functionality at our disposal, leťs have a look at storing simple 
JavaScript objects and arrays using our PROlňlEBAPPS. Storage functions. We'll do this by 
creating our webstorage-test. js file, which will be used to power this little storage test 
application: 

$(document) .ready(function() { 

// read the data from local storage for the items 
var items = PROWEBAPPS. Storage. get("listiteins"); 
var loadTicks = new Date() .getTime(); 

function displayltemsO { 

loadTicks = new Date() .getTime(); 

$("#items li[class!='header' ]").remove(); 
if (items) { 

// create list items to display the current items 
for (var ii = 0; ii < items. length; ii++) { 

var itemAge = Math.floor((loadTicks - items[ii] .created) / lOOO); 

$("#items") .append("<li>" + items[ii] .title + " (created " + itemAge + 

"s ago)</li>"); 

} // for 

} 
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else { 

$("#items") .append("<li>No items</li>"); 



// initialize the items array 
items = []; 
} // if..else 
} // displayltems 



// button click handlers go here 
displayltemsO; 

}); 

The preceding code is very simple and is designed to retrieve an array of items 
(listitems) from localStorage and display tliem on tlie screen. Witli tlie code as it was 
before (witliout add or clear functionality defined), loading the page generates HTML 
output, as displayed in Figuře 3-2. 

SfflO 11:30 AM 



Web StorageJSON Wrapper 
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No items 



New Item 



Title 



Add 
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Figuře 3-2. The Web Storage test application page 



As there are no items currently in storage (the PROWEBAPPS. Storage. get function 
currently returns null), we display "No items" on the screen. Leťs implement the add 
and clear button click handlers to populate and save the array: 

$("#add").click(function() { 
items. push({ 

title: $("#newtitle").val(), 
created: new Date() .getTime() 

}); 

// save the items 

PROWEBAPPS . Storage . set ( "listitems" , items) ; 

displayltemsO; 



}); 



$("#clear").click(function() { 
items = null; 

PROWEBAPPS . Storage . remove( "listitems" ) ; 

displayltemsO; 

}); 

Once again, this is very simple code. In the case of the add handler, we push a new 
object onto the array using the title of the item and the current date time (represented in 
milliseconds), save the items to storage, and then refresh the display. 

The clear handler is even simpler. We reset the items variable statě back to null, 
rennove listitems from local storage, and then update the display. 

Local vs. Session Storage 

As shown in the code previously, there is no difference between using localStorage and 
sessionStorage— not in terms of the actual interaction at least. In fact, the oniy real 
difference is the length of time the data is actually stored and what the data considers to 
be its owner. 

In the case of local storage, the data is persistent and will not be removed uniess iťs 
requested to be removed by the user (e.g., by using the browser settings). 

In the case of session storage, the data lasts oniy as long as the browsing context 
(which is usually terminated when the browser window closes). Additionally, browsers 
will maintain separate sessionStorage objects for separate windows or tabs; local 
storage, on the other hand, will be shared between windows and tabs. 

^ 

NOTE: In doing some detailed analysis of how multiple windows/tabs interact with Web Storage, 
it bacáme clear that the implementation of the PROWEBAPPS . Storage module currently i 
contains a flaw. It is currently possible for two windows to overwrite each other's changes in Ě 
j localStorage. In sessionStorage, however, there are nevěr collisions. '^^^^^fljjjfl 

For both localStorage and sessionStorage, data is stored on a per-origin basis. An origin 
refers to the site from which the page was loaded, and basically means that site B will 
not be able to access client-side data created by site A (which makes sense). 

The Web SQL Database 

Now that we have worked with the Web Storage API, iťs appropriate that we get 
acquainted with Web Storage's cousin— the Web SQL Database. Given the more 
complicated nature of this storage API, we will cover it briefly here and then run through 
more concrete examples when we build our GeoMiner application later in the book. 



The implementation of the Web SQL Database feels very much like interacting with a 
typical Ajax handler (the SQL aside), as interactions with the API are primarily 
asynchronous operations. Web workers (which oniy have sparse support on mobile 
browsers at the time of writing) also have access to a synchronous implementation — 
which is appropriate given their threaded execution context. 

At a high level, we can summarize the HTML5 Web SQL Database implementation in 
about three methods: 

■ openDatabase: Used to open/create a database. This method takés five 
arguments: 

■ databaseid: The ID of the database. 

■ version: A string identifying the version of the database. This can 
be used to implement particular version-update scripts (more 
Information on this is provided in Chapter 4). 

■ description: A human-readable description of the database. 

■ estimatedSize: The estimated slze of the database (in bytes). 

■ creationCallback: A callback that will be executed once the 
database has been opened/created (not implemented in all 
browsers). 

■ transaction/readTransaction: Used to open a transaction for the 
execution of one or more SQL statements. The transaction method is 
used for INSERT/UPDATE/DELETE operations, and the readTransaction is 
used for SELECT statements. This method onIy accepts one argument: 

■ callback: The callback function that will be called when the 
transaction has been opened. When the callback is executed, it 
passes in a single argument for the transaction instance. 

■ executeSql: Used to run an SQL statement within a transaction. This 
method takés four arguments: 

■ sqlText: The SQL statement to execute against the database. 

■ sqlParameters: An array of values for the parameters included in 
sqlText statement. Parameters are specified in the SQL using a 
question mark (?). 

■ completionCallback: A function callback that will be invoked 
when the SQL statement has been successfully executed. In the 
case of a SELECT statement, results will be returned as a second 
argument in the callback. A transaction argument is returned as 
the first argument in all cases if the callback is specified. 

■ errorCallback: A callback that will be invoked if there are issues 
with the SQL statement or database. 



While we won't go through the code in detail liere, if you are interested In 
worl<ing through how our previous example of saving objects wouid look using 
the Web SQL Database instead of Web Storage, we have provided an example 
implementation at the following location: 

http://sidelab.com/code/pawa/snippets/03/webstorage-test-webdb.js. 

Given the amount of materiál there is to cover, we will focus on Implementing a local 
database reading and writing usIng the Web SQL Database API. ThIs wlll be covered In 
the next example. 

Saving To-Do List Items witli a Client-Side Database 

In thIs exercise, we will use the Web SQL Database API to save to-do list Items to a 
client-side database for later use. We will work with the methods outllned previously to 
do this. 

Begin by creating a submodule called TODOLIST. Storage In your JavaScript appllcation 
code. ThIs module wlll be responsible for handling interactlon with the database for the 
appllcation. It Is important to encapsulate this functlonallty, as It glves you the optlon to 
use an alternativě storage mechanism (e.g., the Web Storage API) at a later date without 
affecting the rest of the appllcation code. 

The following code shouid be added to the module definition In the todolist. js flle 
(remember to include a comma If this lsn't the last member of the module array): 

storage: (function() { 

// open/create a database for the appllcation (expected slze ~ lOOK) 

var db = openDatabase("todollst"j "1.0", "To Do List Database", 100 * 1024); 

// check that we have the required tables created 
db.transaction(function(transaction) { 
transaction.executeSql( 

"CREATE TABLE IF NOT EXISTS task(" + 

" name TEXT NOT NULL, " + 

" description TEXT, " + 

" due DATETIME);"); 

}); 

return { 

saveTask: f unction(task, callback) { 

db.transaction(function(transaction) { 
transaction.executeSql( 

"INSERT INTO task(name, description, due) VALUES (?, ?, ?);", 
[task.name, task. description, task.due] 

); 

}); 

} 

}; 

})() 

At this stage, TODOLIST. Storage has oniy two functlons: 



■ To create/open a client-side database called todolist, and to ensure 
that the required task table exists, creating it if required 



■ To save a to-do list item into the task table 

We then create what might be called a DTO (data transfer object) or POJO (plain-old 
Java object) in other languages to capture the details of a to-do list item. In future 
exercises, we will refer to these as POJOs, since the acronym works almost as weil for 
JavaScript as it does for Java. 

As per the preceding Storage code, Task is added to the module definition of 
todolist. js: 

Task: f unction(params) { 
params = jOuery.extend({ 
name: "", 
description: "", 
due: null 
}, params); 

// initialize self 
var self = { 
id: nulí, 

name: params. name, 

description: params. description, 

due: params. due ? new Date(params.due) : null 

}; 



return self: 



) 



r 




NOTE: While we have a preference for using POJOs to capture details about an object in our 
application, this isn't aiways the best way to go. You can see in the preceding case that Task 
adds very little extra value in this early stage. Personally, we find that architecting an application 
in this way provides some benefits once it reaches a certain slze and complexity, but can feel 
like a waste of time initially. 

When it comes to actually saving Task, we'll provide an alternativě implementation that will 
work without the POJO if that is your preference. 

One finál plece of supporting code is required and, if you have worked with jQuery and 
web apps before, you have probably built something like this yourself previously. To 
save yourself from writing the same code time and time again to extract form values 
from a form and map them into an object, you can use something like the following code 
to make that process more streamlined (given that you are able to use consistent 
naming for form fields, object properties, etc). 

The following code shouid be added to the module definition for the prowebapps. js file 
(remember, a trailing comma may be required depending on where you add the code in 
the module): 




getFortnValues: function(form) { 
var values = {}; 

// iterate through the form values using jOuery 
jOuery(fortn) .f ind(" : input") .each(function() { 
// get the name of the field 

var fieldName = thls.name.replace(/''.*\[(\w+)\]$/, 

// set the value for the field 
values [fieldName] = this. value; 

}); 

return values; 

} 

Now that all the building blocks are in pláce, leťs go back and change the submit 
handler that was left blank when we finished Chapter 2 so that it contains some code 
that will actually save the to-do list item: 

$("#taskentry") . validate({ 

submitHandler : f unction(form) { 

// get the values from the form in hashmap 

var formValues = PROWEBAPPS.getFormValues(form); 

// create a new item to save to the database 
var item = new TODOLIST.Task(formValues); 

// now create a new task 
TODOLIST.Storage.saveTask(item); 

}, 

showErrors: function(errorMap, errorList) { 
// code from chapter 02 

} 

}); 

Savlng a new to-do item is now a simple three-step process: 

1. Getting the values of the fields in the form as a JavaScript key/value pair array 

2. Creating a new item from those form values 

3. Asking the Storage module to save the item for us 

Running this code on an Android handset or emulátor is quite unsatisfying, as we 
haven't bulit our interface for displaying items yet. To get some confidence that this is 
actually working, leťs have a look in Chromé, using the Chromé developer tools. As 
outlined in Chapter 1 , a WebKit-based desktop browser is an invaluable tool when it 
comes to debugging mobile apps— my personál preference is Chromé. 

So, we provide the form some data. As shown in Figuře 3-3, i am going to give myseif a 
to-do of mowing the iawn before the end of 201 1 (iťs not one of my strong points). 
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Figuře 3-3. The Create Task form with sample data displayed in Chromé 



On submitting the form, the data passes the validation checks that we set up in the last 
chapter and thus proceeds to save the data according to the logic that we set up in the 
submit handler. Having a look in the Storage tab in the developer tools, we can see that 
our data was indeed saved to the local database. Figuře 3-4 shows the Chromé 
developer tools. 
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Figuře 3-4. The new task is saved, and can be seen using the Storage inspector in the Chromé developer tools. 



As promised, if you are not a fan of using POJOs and the like to encapsulate data 
moving around in your application, the submit handler code can be modified to the 
following: 

$("#taskentry").validate({ 

submitHandler : function(form) { 

// get the values from the form in hashmap 

var formValues = PROWEBAPPS.getFormValues(form); 

// now create a new to-do list item 
TODOLIST. Storage . saveTask(f ormValues) ; 

}, 

showErrors: function(errorMap, errorList) { 
// code from chapter 02 

} 

}); 

As it stands with the code in the Storage module, the date Is saved as entered. Figuře 3- 
5 shows that the database holds a value identical to what was entered, which indicates 
that this value is probably saved as a string. 
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Figuře 3-5. The results of not converting a string to a Date object before inserting it into the database 



You can see the second entry has been added as is. In reality, this is also the case for 
the first entry too, as what is displayed here is simply the toString representation for a 
JavaScript Date object (as we converted the form value to a Date in the Task POJO). 

CAUTION: The preceding behavior is interesting, given that we explicitly defined the due field as 
a DATETIME type in our CREATE TABLE statement While this won't cause any real issues in our 
application here, we think it is worth noting that with current implementations of the SQL Web 
Database you may need to test your data on read operations in addition to writes, as you may not 
be able to trust that the data in the database is of the type you expect. 

To confirm this behavior, try tweaking the code to see if you can actually push a string value into 
the due field. You will find that you can. This appears to be consistent with the way SQLite 
handles DATETIME columns. For more information, check out the following URL on the SQLite 
site: www . sqlite . org/datatype3 . html. 



Database Versioning and Upgrades 



The HTML5 implementation of the Web SQL Database has aiready been quite weil 
thought through, and provides a mechanism to apply version changes to our client-side 
databases when a new version of our application is deployed. This involves the use of 
the changeVersion method on an opened database. The method allows you to specify 
the old version, the new version, and a transaction callback to execute, in order to apply 
any updates required to move from one version to the next. Additionally, optional error 
and success callbacks can be supplied to monitor and respond to those particular 
response conditions. 

For instance, in the next chapter we are going to add some functionality to our to-do list 
application to allow a user to mark items as complete. This is obviously a good idea, but 
the database is clearly lacking a pláce to store a completed flag or date. Time to fix that 
and create version 1 .1 of our database. 

The following code shows how we can replace our originál openDatabase call in the 
TODOLIST.Storage module with one that can handle opening either version 1.1 or version 
1 .0 of the database, and upgrade version 1 .0 appropriately: 

var db = null; 
try { 

db = openDatabase("todolist", "l.l", "To Do List Database", 100 * 1024); 

// check that we have the required tables created 
db. transaction (funct ion (transaction) { 
transaction. executeSql( 

"CREATE TABLE IF NOT EXISTS task(" + 

" name TEXT NOT NULL, " + 

" description TEXT, " + 

" due DATETIME, " + 

" completed DATETIME);"); 

}); 

} 

catch (e) { 

db = openDatabase("todolist", "1.0", "To Do List Database", 100 * 1024); 

// check that we have the required tables created 
db. transaction (funct ion (transaction) { 
transaction. executeSql( 

"CREATE TABLE IF NOT EXISTS task(" + 

" name TEXT NOT NULL, " + 

" description TEXT, " + 

" due DATETIME);"); 

}); 

db.changeVersion("l.O", "l.l", f unction(transaction) { 

transaction. executeSql("ALTER TABLE item ADD completed DATETIME;"); 

}); 

} 

We'll be honest here and say that we're not huge fans of this implementation. It works, 
but we wonder how scalable it is when you are rolling out your 13th application update 



and corresponding database change. (Of course, one database change per app update 
wouid be very bad planning, but you get our point.) 

Summary 

We have explored two powerful mechanisms for storing data on the client side in this 
chapter. Wliile not one of tlie sliiniest toys in the HTIV1L5 bag of tricks, iťs certainiy one 
of the ganne changers. Being able to store different types of data on the client side is 
going to create many opportunities for mobile web apps over the next few years. 

In addition to the actual mechanics of Web Storage and the Web SQL Database, we 
also investigated ways of effectively encapsulating that and other functionality in web 
apps using the JavaScript module pattern. You can probably tell how important we think 
it is for building serious apps using JavaScript, but we premise we'll back off a little in 
the following chapters. 

In the next chapter, we will finish our to-do list application by adding a view to display 
our to-do list items, and also a way to mark them as complete. At this point, we will go 
beyond single-page examples into a multiple-view/screen application. We will 
investigate ways to build this kind of functionality as weil as briefly explore libraries that 
offer this functionality aiready. 




Constructing a Multipage 
App 

Now that we have the ability to save tasks in our to-do list application, iťs time to build 
our display screen and add the ability to complete tasl<s. Tliis will bring our to-do list 
application to the point that it can actually be used for creating, viewing, and completing 
tasks. 

With data now being saved to the client-side database, leťs create a display screen so 
that we can keep track of all those things we have to do (sigh). We are going to be 
working toward building a display that shows the next five things that need to be done 
(in due date) order. 

Once we have done this, we will be at a point where our to-do list application has 
multiple screens. While we couid implement these using separate HTML pages, that 
wouid result in page loads that aren't required. This is best avoided, so we will 
implement some functionality that you will find in the likes of jQTouch 
(http : // jqtouch . com) and iUI (http : //code . google . com/p/iui) for creating a single 
HTML document that contains multiple application screens. 

Single HTML File, Multiple App Pages 

Before we get into building our main to-do list application page, leťs work through 
adding some additional styles to our proui.css file to handle setting up divs for display 
and also showing a simple application menu at the base of the screen. 

Firstly, leťs look at what is required to correctly display oniy one page when the 
application page loads: 

div.view { 

display: none; 
padding: O 6px; 

} 

div#main { 
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display: block; 

} 

This simple CSS sets all div elements with the class view to be hidden by default. The 
second style declaration simply says that, if we have a div with an ID of main, that 
shouid override the view class and display the block. 

<div id="main" class="view"> 

<hl>To Do List</hl> 

<p>Application Main Page</p> 
</div> 

<div id="add" class="view"> 

<hl>Create Task</hl> 

<p>Add Form Goes Here</p> 
</div> 

The preceding HTML fragment wouid generate a display with a title bar showing "To Do 
List" and the text "Application Main Page." On page load, there wouid be no visibility of 
either the "Create Task" header or the "Add Form Goes Here" text. 

Additionally, leťs just make a simple change to the existing proui.css stylesheet styles 
to display the hl.fancy style if an hl tag is contained within a div of class view: 

hl.fancyj div. view hl { 

bacl<ground: -webl<it-gradient(linear, left top^ left bottom, color-stop(0.0, 
#666566), color-stop(0.5j #3A3A3A), color-stop(0.5, #222222), color-stop(l.O, #000000)); 

-webkit-box-shadow: O 2px ipx #AAAAAA; 

-webkit-border-bottom-left-radius: 6px; 

-webkit-border-bottom-right-radius : 5px; 

font-size: l.lem; 

color: white; 

padding: lOpx 8px; 

margin: O O 6px 0; 

text-align: center; 

} 

In the to-do list application, we will create a bottom menu bar that will contain the action 
links that are relevant for the current view. This will meet the requirements of both items 
1 and 2, and is consistent with native applications on Android. 

NOTE: We will be using the same screen real astate and Ul styling to meet both of the preceding 1 
requirements for Android. If you have experience with other mobile platforms, however, then you I 
will know these user interactions are often done differently depending on the platform. In that ^ 
oase, the location of action and back buttons will vary. 

Choosing an appropriate formatting style that is going to suit the majority of devices is difficult, 
which is why using a third-party Ul suitě is highiy recommended. Unfortunately, at this time, 
most Ul frameworks are geared toward an iPhone look and feel, and building an Android web app | 
that feels like an iPhone app isn't really what we are after here. I 



We will get started by having a look at some CSS styling to create such an action bar: 



ul#menu { 

position: fixed; 
bottom: Opx; 
margin: 0; 
padding: 5pxj 
list-style-type: none; 

background: -webkit-gradient(linear, left top^ left bottom, color-stop(0.0, 
#666666), color-stop(0.5, #3A3A3A), color-stop(0. 5, #222222), color-stop(l.O, 
#000000));; 

width: 100%; 

} 

ul#menu li { 
margin: 0; 
float: left; 
padding: 4px lOpx O 0; 

} 

ul#menu li a { 
color: white; 
font-weight: bold; 

} 

This CSS, when applied with the following menu list (inserted into the HTML just before 
our previous view declarations), will generate a display as per tine one in Figuře 4-1 . 

<ul id="menu"> 

<li><a href="#add">Add</a></li> 
</ul> 

Slfflíl 4:38 PM 



Application Main Page 



Actd 



Figuře 4-1 . Our application main view with an action menu bar 
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While the preceding HTML fragment demonstrates how to construct the menu for 
display to the screen, it is not something that you wouid or shouid manually construct in 
HTIVIL. Instead, we need an intelligent way to tell our application wliat tlie valid menu 
items for each screen are, and, additionally, wliat action shouid be taken for any given 
menu item. 



Creating a View Manager 

There are a variety of different approaches that couid be used to prevent our having to 
write static HTML over and over again. For instance, we couId use CSS classes as per 
the jQuery validation plug-in that was used in the previous chapter, and then build some 
JavaScript code to read the Information out of the CSS classes and configure our 
application. In this particular case, however, we are going to write a ViewManager 
submodule for our prowebapps. js file that we will configure from our application 
JavaScript file. 

The outline of the PROWEBAPPS. ViewManager module is shown here: 

ViewManager: (function() { 
var views = {}; 
var activeView = null; 

function switchView(oldVieWj newView) { 

// will switch views here 
} // switchView 

var subModule = { 

activate: f unction(viewld) { 
// save the old view 
var oldView = activeView; 



for a div 



// if a view id has been specified, but doesn't exist in the views, check 

if (viewld && (! views[viewld]) && (jOuery("#" + viewld) .get(o))) { 
subModule. define({ 
id: viewld 

}); 

} // if 

// update the active view 

activeView = viewld ? views [viewld] : null; 

// update the associated ui elements 
switchView(oldVieWj activeView); 



getActiveView: function() { 

return activeView ? jOuery("#" + activeView. id) : null; 

}, 

define: f unction(args) { 
args = jOuery .extend({ 
id: 

actions: [] 



}. args); 



// if the id is specifled, add the view to the list of defined views 
if (args. id) { 

views [args. id] = args; 

} // if 

} 

}; 

return subModule; 

})(); 

An application wouid then call PROWEBAPPS.ViewManager.define to define a new view 
with its associated actions (we'll see an example soon). The static function define allows 
US to register new views with the view manager, and activate sets the module variable 
activeView to match the specified view. We then make a call to switchView to update 
the Ul elemente based on the change in active view. 

Expanding on the switchView stub, we implement the following priváte functions to 
implement changing the view: 

function getViewActions(view) { 
var html = ""; 

for (var ii = 0; view && (ii < view. actions. length); ii++) { 
html += "<li>" + view.actions[ii] .getAnchorQ + "</li>"; 

} // for 

return html; 
} // getViewActions 

function getAction(view, actionid) { 

// extract the id portion from the action id 
actionid = actionid. replace(/''action_(\d+)$/i, "$l"); 

// find the specified view in the active view and execute it 
for (var ii = 0; ii < view. actions. length; ii++) { 

if (view.actions[ii] .id == actionid) { 
return view.actions[ii]; 

} // if 
} // for 

return null; 
} // getAction 

function switchView(oldView, newView) { 
var ii, menu = jOuery("#menu").get(0); 

// switch the views using jOuery 

oldView ? jOuery("#" + oldView.id).hide() : null; 

newView ? ]Ouery("#" + newView.id).show().trigger("activated") : null; 

// if we have a menu, then update the actions 
if (menu) { 

// clear the menu and create list items and anchors as required 
jOuery (menu) .html(getViewActions (activeView)); 



// attach a click handler to each of the anchors now in the menu 




jOuery(menu) .findCa") .click(-Function(evt) { 
var action = getAction(activeView, this.id); 
if (action) { 

action. executeO; 

evt . preventDefault ( ) ; 
} // if 

}); 

} // if 
} // switchView 

At this stage, the priváte switchView function has two purposes: 

■ To hide the current view if active, and show the new view. Also notice 
the call to the jQuery trigger method on the new element. We will be 
making use of that later in this chapter. 

■ To check for the presence of a #menu element. If it exists, populate it 
appropriately with links to the relevant actions for the active view. 
Once the menu has been built, the jQuery click function is used to 
handle finding and executing the action when a link is clicked. 



Implementing View Actions 

With the ViewManager functional, it is now just a matter of building some actions that the 
ViewManager can make use of. We can then integrate this new functionality into our to- 
do list app. 

We will start with the PROWEBAPPS.ViewAction class: 

ViewAction: f unction(args) { 
args = jOuery .extend({ 
labei: "", 
run: null 
}, args); 

var self = { 

id: actionCounter++j 

getAnchor: function() { 

return "<a href='#' id='action_" + self. id + '">" + args.label + "</a>"; 

}, 

execute: function() { 
if (args. run) { 

args. run. apply(this, arguments); 
} // if 

} 

}; 

return self; 

} 

This is a base class that knows how to display itself as an anchor tag, using the 
getAnchor method, and also has an execute method for executing the action. 
Additionally, note the reference to a variable called actionCounter that is being assigned 
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to the id member of a new ViewAction object. This variable is defined within the scope 
of the PROWEBAPPS main module as such: 

PROWEBAPPS = (functionO { 
var actionCounter = 0; 

})();" 

The variable will exist and maintain statě for the life of the page/application, so we can 
use it as a counter for the actions and it will generate unique IDs for the anchors that are 
created. At no time, however, is the variable into globál scope. This is one of the big 
attractions of using something like the module pattern in JavaScript code. 

Leťs now create a PROWEBAPPS. ChangeViewAction class that actually does something 
when iťs executed: 

ChangeViewAction: f unction(args) { 

// if the target is not defined, then raise an error 

if (! args. target) { 

throw new Error ("Unable to create a ChangeViewAction without a target 
specified. "); 

} // if 

// prep the label to equal the target if not defined 
if (! args. label) { 

args. label = args. target; 
} // if 

return new module. ViewAction(jOuery.extend({ 
run: function() { 

module. ViewManager.activate (args. target); 

} 

}, args)); 

} 

At first glance the preceding code is a little confusing, but leťs step through it and 
understand what is happening: 

1. We first check to see that a target has been defined for the simple args object 
that has been passed to the class constructor; if not, an exception is raised. 

2. If a label hasn't been defined in the constructor args, we assign the target value to 
the label to prevent displaying an empty anchor tag. 

3. If all is weil, we then create a new PROWEBAPPS. ViewAction and supply a run 
function handler. When the new ViewAction is subsequently executed, this 
function will be executed. 

TODOLIST = (functionO { 
// define the module 
var module = { 

}; 

// define the main view 
PROWEBAPPS . ViewManager . define ({ 
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id: "main"j 
actions: [ 

new PROWEBAPPS.ChangeViewAction({ 

target: "add", 

label: "Add" 

}) 

] 

}); 

return module; 

})(); 

And voila! We are rewarded with a display that looks exactly like Figuře 4-2. We guess 
this couid be a little disheartening, but remember the following: 

■ It actually does something now. 

■ We are beginning to build up a pretty usefuí toolkit in the 
prowebapps. js file tínat will definitely make our lives easier— eventually. 



Create Task 



Add Form Goes Here 



Figuře 4-2. Clicking the Add link actually does something now. 



Note tínat we didn't define the "add" view, but the view still switched successfully. This 
is thanks to some code in the ViewManager.activate function that checks to see if a 
view actually does exist, regardless of whether it was explicitly defined or not. 



Building the Application's Main Screen 

Now that we have built some application code that will allow us to build more than just a 
simple application, we are ready to start building those separate screens. Leťs start by 
building the main screen of our application. 

For both the main screen and the to-do list task display, we'll begin by putting together 
a screen mockup (\'m a big fan of Inkscape [www.inkscape.org] for this kind of thing), 
and then building the display to match that layout. Figuře 4-3 shows the mockup for the 
to-do list application home page. 



@ 3:06 1 



To Do List 



Tásk descnpfíon goes hera (if derned) 



DUEfM: 5days 



Show All Tas ks 
Add New 



Figuře 4-3. To-do list application home page mockup 



The layout of the home screen is designed to be very simple. Rather than showing the 
complete lists of tasks, just the most important task is shown — in an attempt to stop us 
from getting distracted (trust me. Tm very distractable). Readers of the Lifehacker blog 
(http://lifehacker.com) may weil be familiar with the technique. 

The HTML for a static replacement for the main div is listed here: 

<div id="main" class="view"> 
<hl>To Do List</hl> 
<div class="task"> 

<h3>Task: <span class="task-nařne">Mow the Lawn</span></h3> 
<p class="task-description">Task description goes here</p> 
<p class="task-due"> 

<label>DUE IN:</label> 

<span class="task-daysleft">5 days</span> 

</p> 

<ul class="task-actions"> 
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<li class="right"><a href="#" class="task-complete">COMPLETE TASK</a></li> 
<li><a href="#" class="task-start">START WORKING</a></li> 
</ul> 
</div> 

<ul class="buttons"> 

<li><a class="changeview" href="#alltasks">Show All Tasks</a></li> 

<li><a class="changeview" href="#add">Add New</a></li> 
</ul> 
</div> 

Notice here that we have a number of HTML elements that will end up displaying the 
actual task details once the application logic is written. For now, placeholder values are 
included. 

Without any CSS to style this HTML (see Figuře 4-4), the view looks pretty ordinary, so 
we add the following styles to the todolist.css file for the formatting of the task box, 
name, description, and so on: 

div. task { 

margin: 8px 4px; 

} 

div. task h3 { 

border: ipx solid #ff6600; 
background: #ff7f2a; 
color: white; 

-webkit-border-top-left- rádius: 5px; 
-webkit-border-top-right-radius : 5px; 
margin: 0; 
padding: 8px; 
font-size: 0.8em; 



div. task p { 
margin: 0; 

background: #e6e6e6; 
border-left: ipx solid #b3b3b3; 
border-right: ipx solid #b3b3b3; 
padding: Bpx; 



p.task-due label { 
font-weight: bold; 
width: 70px; 
float: left; 



Slffií^ 12:21 



To Do List 



Task: Mow the Lawn 

Task description goes here 
DUE IN: Sdays 

• C0MPLETETA5K 

• START WORKING 

• Show Ml Tasks 

• Add Nevj 



Figuře 4-4. The main screen of our app is showing a distinct lack of style. 



Add the following for formatting the task actions that are displayed beneath the task 
details: 

ul.task-actions { 

background: #b3b3b3; 
border: ipx solid #b3b3b3; 
color: white; 
padding: 8px; 

-webkit-border-bottom-left-radius: 5px; 
-webkit-border-bottom-right-radius: 5px; 
margin: 0; 

list-style-type: none; 

} 

ul.task-actions li a { 
color: whitej 
text-decoration: none; 
font-weight: bold; 
font-size: 0.8em; 

} 

ul.task-actions li.right { 
padding: 4px 0 0 0; 

} 

Finally, we add a definition for elements matching the right class to float right: 

.right { 

float: right; 

} 
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While the task details area of the screen now looks like the mockup, there is still some 
work to do to show buttons instead of links— as shown in Figuře 4-5. This is acinieved 
by adding the following CSS to the proui.css file: 

ul. buttons { 

margin: 4px 0 0 0; 
padding: 0; 

list-style-type: none; 

} 

ul. buttons li { 

margin: 4px 4px lOpx 4px; 

} 

ul. buttons li a { 
display: blocl<; 

bacl<ground: -webl<it-gradient(linear, left top, left bottom, color-stop(0.0, 
#b3b3b3), color-stop(0.4, #666666), color-stop(l.O, #333333)); 
color: white; 
text-decoration: none; 
padding: 8px; 
text-align: center; 

-webl<it-box-shadow: O 2px 2px #333333; 
-webl<it-border-radius: 6px; 

} 

SUffle 12:18 PM 



To Do List 



Task: Mow the Lawn 



Task description goes here 



DUEIN; Sdays 




• Show Al[ Tasks 

• Add New 



Figuře 4-5. Task elements styled 



With all the styles applied, this generates a static HTML screen, as shown in Figuře 4-6. 
Iťs definitely starting to look the part. 



mine 12:15 PM 



To Do List 



Task: Mowthe Lawn 



Task description goes here 
DUEIN: Sdays 



START WORKING 



COHPLETETASK 



Show All Tas ks 



Figuře 4-6. The static HTML equivalent to our tiome screen mockup 



Tweaking ViewManager Functionality 

Now that the display is ready, we can continue and update the application logic to make 
the home screen behave the way it should. 

Leťs start by getting rid of the Add link displayed in the globál menu, which is displayed 
here because we have a view definition for the main view from our previous exannples. 
The functionality is still useful, but not required on the Show All Tasks screen, so we'll 
modify the view definition by simply replacing main with alltasks for the view ID. 

// define the all tasks view 
PROWEBAPPS. ViewManager. define({ 
id: "alltasks", 
actions: [ 

new PROWEBAPPS. ChangeViewAction({ 
target: "add", 
label: "Add" 

}) 

] 

}); 

We'll also add some additional code to prowebapps. js to have the ViewManager 
submodule automatically add switching view handling to this and future button lists: 

ViewManager: (function() { 



jOuery(document) .ready(function() { 
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jOuery("a.changeview") .each(function() { 
jOuery(this) .click(f unction(evt) { 

subModule.activate(this.href .replace(/''.*\#(.*)$/, 

evt . preventDef ault () ; 
}); // click 

}); 



}); 

return subModule; 

})() 

If you are not familiar with the jQuery each method, it calis the supplied callback for each 
element that matches the specified selector. At this stage, the callback will be fired twice 
(once for each of the buttons in the list), and a click event will be attached to the 
matching anchor. The handler for the click event calIs the ViewManager.activate method 
to change to that view. We additionally call preventDefault on the event object to 
prevent the browser from attempting to navigate to the referenced named anchor. This 
stops the screen from scrolling back up to the top, which wouid reveal the URL bar 
(which is not what we want). 



Home Screen Storage Requirements 

From here we will write the code required to read the actual task data back out of the 
local database we created in the previous chapter. This is going to involve adding some 
additional methods to our storage wrapper. Once we have created the required methods 
for reading task data, we will add a method that will enable us to mark a task as 
complete. 

^ NOTE: Given some of the data typing we experienced in the previous chapter, we are going 
have to implement things a little differently here. Normally, we wouId ask the SQL database to 
sort the tasks by their due date for us, but, as we are actually dealing with strings, that isn't 
going to be possible. There are ways you can use SQLite to do this, but it is quite complicated 




First, add a getTasks priváte function to the T0D0LI5T. Storage module: 

function getTasks(callback, extraClauses) { 
db.transaction(function(transaction) { 
transaction.executeSql( 

"SELECT rowid as idj * FROM task " + (extraClauses ? extraClauses : ""), 
[], 

function (transaction, results) { 

// initialize an array to hold the tasks 
var tasks = []; 

// read each of the rows from the db, and create tasks 
for (var 11 =0; 11 < results. rows. length; 11++) { 

tasks. push(new module. Task(results. rows. ltem( 11))); 
} // for 



callback(tasks); 



); 



} 



}); 

} // getTasks 

This function requests all the data stored in the task table of the database and 
populates an array with Task objects. This array is tlien passed through in the getTasks 
function call. The method is also written so that it accepts an optional parameter, 
extraClauses, which allows the function to add extra SQL clauses to the SELECT 
statement. This couid include WHERE statements (as per the code following) or 
additionally ORDER BY statements that wouid then help to sort the tasks in a particular 
order. 



\UTION: The reference here to results.rows.item(index) is not consistent with the 

current draft of the Web SQL database specification. It is, however, the behavior that is 
implemented in most browsers presently. While we wouId have expected that browsers wouId 
change to match the specification, the move by the W3C to deprecate the specification will 
probably mean that the functionality_wil.l remain as is. 



Leťs add some methods to the Storage module that will allow those using the module to 
access the saved tasks; 

Storage: (functionO { 



var subModule = { 

getIncompleteTasks : function (callback) { 

getTasks(callback, "WHERE completed IS NULL"); 

}. 

getTasksInPriorityOrder: f unction(callback) { 

subModule. getIncompleteTasks (function (tasks) { 
callback(tasks.sort(function(taskA, taskB) { 
return taskA.due - taskB. due; 

})); 

}); 

}, 

getMostImportantTask: function(callback) { 

subModule. getTasksInPriorityOrder (function (tasks) { 
callback(tasks.length > o ? tasks[o] : null); 

}); 



}; 

return subModule; 

})() 

Here we have added three methods: 




■ getIncompleteTasks: Used to return tasks that have not been marked 
as complete. Notice that we make use of the extraClauses parameter 
of the getTasks function to restrict the result set. 

■ getTasksInPriorityOrder: Used to return incomplete tasks in due date 
order. Note the use of the JavaScript Array.sort nnethod here to sort 
the results. While we wouid normally implement this using an ORDER BY 
statement in our SQL call, some of the datetime mismatches make it 
simpler (but probably less efficient) to implement in JavaScript. 

■ getMostImportantTask: Used to return the first of our tasks from the 
getTasksInPriorityOrder method. 

We now need to modify the saveTask method to allow us to update existing tasks, in 
addition to creating new tasks. 

Additionally, the saveTask method is modified to support both creating new tasks and 
updating existing tasks: 

saveTask: f unction(task, callback) { 

db.transaction(function(transaction) { 

// if the task id is not assigned, then insert 
if (! task. id) { 

transaction.executeSqI( 

"INSERT INTO task(name, description, due) VALUES (?, ?, ?);", 
[task.name, task. description, task. due], 
function(tx) { 

transaction.executeSql( 

"SELECT MAX(rowid) AS id from task", 
[], 

function (tx, results) { 

task. id = results. rows. item(o) .idj 
if (callback) { 
callbackO; 
} // if 

} 

); 

} 

); 

} 

// otherwise, update 
else { 

transaction.executeSql( 
"UPDATE task " + 

"SET name = ?, description = ?, due = ?, completed = ? " + 
"WHERE rowid = ?;", 

[task.name, task. description, task. due, task. completed, task. id], 
function (tx) { 

if (callback) { 
callbackO; 

} // if 

} 

); 

} // if..else 

}); 

} 
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NOTE: If you haven't been working with JavaScript callbacks for long, it will take a little while to 
get used to the asynchronous behavior here. In very simple terms, we need to move away from 
linear thinking. Instead of thinking, "A occurs, then B occurs, and then C occurs," we shouid i 
think, "A occurs, we initiate B, C occurs, B's ready, so it completes." It definitely takés some ĚjM 
getting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^B 

We are almost at the point where we can actually replace some of those placeholder 
values on the main screen with real data. Before we do that, though, leťs quickly tweak 
our Task class to include a getDaysDue method to report the number of days until the 
task is due. We'll also add a complete method that will allow us to mark the task as 
complete: 

Task: f unction(params) { 
params = jOuery.extend({ 
id: null, 
name: "", 
description: "", 
due: null 
}, params); 

// initialize self 
var self = { 

id: params. id, 

name: params. name, 

description: params. description, 

due: params. due ? new Date(params.due) : null, 

completed: null, 

complete: function() { 

self .completed = new Date(); 

}, 

getDaysDue: function() { 

return Math.floor((self .due - new Date()) / MILLISECONDS_TO_DAYS); 

} 

}; 

return self; 

} 

The MILLISECONDS_TO_DAYS constant is defined privately in the TODOLIST module: 

TODOLIST = (functionO { 

var MILLISECONDS_TO_DAYS = 86400000; 



}); 



Wiring Up the Home Screen 



With the required methods added to the TODOLIST.Storage module, and a Ul to display 
our task information, we are now ready to start bringing those pieces together. 
Thankfully, this is made simple given jQuery's event systém and the trigger call we 
implemented earlier. Essentially, we need to bind to listen for the activated event, and 
then do something in response to that event occurring. We will implement the bind 
handler and code that is called as a result in three places. First, we modify the 
document. ready event listener to attach event handlers to various views (just the main 
view at this stage) and then activate the main view on load of the application: 

$(document) .ready(function() { 



// bind activation handlers 

$("#main") .bind("activated"j TODOLIST.activateMain); 

// initialize the main view 

PROWEBAPPS . ViewManager . activate( "main " ) ; 

}); 

Next, we implement the TODOLIST.activateMain module function that is invoked when 
the activated event is received for the #main element: 

activateMain: function() { 

TODOLIST.Storage.getMostImportantTask(function(task) { 
if (task) { 

// the no tasks message may be displayed, so remove it 
jOuery("#main .notasks") .remove(); 

// update the task details 
showTaskDetails("#[nain .task", task); 

// attach a click handler to the complete task button 
jOuery("#main .task-co[nplete").unbind().click(function() { 
jOuery("#main .task") .slideUp(); 

// mark the task as complete 
task.completeO; 

// save the task back to storage 

TODOLIST.Storage.saveTask(task, module. activateMain); 

}); 

} 

else { 

jOuery("#main .notasks") .remove(); 

jOuery("#main .task").slideUp().after("<p class=' notasks '>You have no tasks 
to complete</p>"); 
} 

}); 

} 

You can see in the preceding code that we make the call to our 

TODOLIST. Storage. getMostImportantTask function and pass through a callbackto 

receive the most important task that has been found in the database. Based on whether 



a task was found or not (the database couid be empty), we then either update the 
contents of the main task or hide the contents and let the user know there are no tasks 
to complete. 

The code also attaches an event handler to the Complete Task link (note the jQuery 
unbind to prevent multiple event calis) to handle completing the task. Thanks to the work 
we have put into the Storage module, wiring up the completion handler takés minimal 
code. 

Both in this code sample and the one following, a couple of CSS classes are used. You 
can decide how you want them to look and add something to the application stylesheet 
(todolist.css) according to your tastes. 

Finally, we create a priváte function, showTaskDetails, to do the work of updating an 
HTML div designed for displaying task details with the actual values: 

function showTaskDetails(selector, task) { 
var Container = jOuery(selector) j 
daysDue = task.getDaysDue(); 

// update the relevant task details 

Container. find(" .task-name") .html(task.name); 

Container .find(" .task-description") .html(task.description); 

if (daysDue < O) { 

Container .find(" .task-daysleft") 

.html("OVERDUE BY " + Math.abs(daysDue) + " DAYS") .addClass("overdue"); 

} 

else { 

container.find(" .task-daysleft") 

.html(daysDue + " days") .removeClass("overdue"); 
} // if..else 
} // showTaskDetails 

This yields the various displays, as shown in Figuře 4-7 (depending on your data). 
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Figuře 4-7. The main screen display based on data that is available 



Congratulations, the main page of the application is now complete. This, combined witin 
tine task-adding functionality that we explored in previous cinapters, allows us to create 
tasks and keep track of important ones. We will need to build the show-all-tasks screen 
as weil SO that we can access the other tasks. 

Before we do that, though, iťs time we take a little break and have you cut some code 
(see Exercise 4-1). 



EXERCISE 4-1 : INTEGRATING THE ADD FORM AS AN EXTRA SCREEN 



You now liave tlie required pieces to take tlie code we created in the last chapter in tlie create-tasl<- 
f orm . Iitml fiie and integrate it into tlie todolist . titml file. Additionaily, witii oniy a smáli amount of 
JavaScript, you shouid be abie to return the user to the appiication main screen once they have 
successfuiiy created a new task. 

There are a few things we haven't created yet (such as having a back action automaticaliy added), but we 
will be compieting that in the next section, and this will automaticaily be made avaiiable in your Add view. 



Building the All Tasks Screen 

Once again, we will start with a mockup of the screen (displayed in Figuře 4-8). TIne 
screen, as you might expect, sinows a list of all the outstanding tasks, with the due date. 
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Figuře 4-8. Design mockup ofthe to-do listmain screen 

Based on whaťs displayed in the preceding mockup, we are pretty much covered in 
terms of our Storage methods, as we can both get tasks in priority order and complete 
tasks. This, then, is simply going to be a Ul and wiring exercise. 

It wouid be great if the back button were automatically displayed for any screen that 
isn't the main screen of the application. It will be worth adding some additional code to 
the PROWEBAPPS.ViewManager module to provide us with that functionality. 

Iťs time to implement the Ul. This will involve the following: 

1. Implementing the basic HTML layout in the todolist.html file. 

2. On activation of this screen, reading the current items from the database and 
generating a list of those items. 

3. Handling a user tapping on an individual item. This will show the details (and the 
complete task link) for that item, hiding the previously selected item. Some nice 
jQuery transitions (slideUp, slideDown) will look good here. 

4. Finally, handling a user marking a task as complete. This will be an exercise for 
you. 
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First is the HTML layout. There isn't much required here as most of the display for this 
screen will be dynamically generated using JavaScript: 

<div id="alltasl<s" class="view"> 

<hl class="fancy">All Tasl<s</hl> 

<ul id="tasl<list"> 

</ul> 
</div> 

From here we move on to reading the current items from the database and populating 
the display. This involves some application code to handle activation of the #alltasks 
div. We create the handler method in the TODOLIST module (we put it right after the 
activateMain function added before): 

activateAllTasks: function() { 

TODOLIST. Storage.getTasksInPriorityOrder(function(tasks) { 
// update the current tasks 
currentTasks = tasks; 

populateTaskList(); 

// refresh the task list display 
jOuery("ul#tasklist li") .click(function() { 
toggleDetailsDisplay(this); 

}); 

jOuery("ul#tasklist a.task-complete") .click(function() { 
// complete the task 
alert("complete the task"); 

}); 

}); 

} 

You can see that this code updates a variable called currentTasks, and then calis a 
function called populateTaskList, and finally attaches event handling to the newly 
created list items (assuming there are tasks). If a list item is clicked, the 
toggleDetailsDisplay function is called to display the description and complete button 
for that task. 

The currentTasks variable shouid be created in the TODOLIST module scope so that any 
code that wouid like to access this variable can do so: 

TODOLIST = (functionO { 

// define an array that will hold the current tasks 
var currentTasks = []; 

// define the module 
var module = { 

}; 



return module; 

})(); 



We then create our populateTaskList function as a priváte function in tlie TODOLIST 
module scope: 

function populateTaskList() { 
function pad(n) { 

return n<lO ? '0'+n : n; 

} 

var listHtml = "", 

monthNames = ["3m" , "FEB", "MAR", "APR", "MAY", "DUN", "]UL", "AUG", "SEP", 
"OCT", "NOV", "DEC"]; 

// iterate through the current tasks 
for (var ii = 0; ii < currentTasks.length; ii++) { 
var dueDateHtml = 

"<ul class='calendar right'>" + 

"<li class='day'>" + pad(currentTasks[ii] .due.getDate()) + "</li>" + 
"<li class='month'>" + monthNames[currentTasks[ii] .due.getMonth() ] + 

"</li>" + 

"<li class='year ' >" + currentTasks[ii] .due.getFullYear() + "</li>" + 
"</ul>" j 

// add the list item for the task 

listHtml += "<li id='task " + currentTasks[ii] .id + "'>" + dueDateHtml + 
"<div class='task-header'>" + currentTasks[ii] .name + "</div>" + 
"<div class= 'task-details ' >" + 

currentTasks[ii] .description + "<br />" + 

"<a href='#' class='task-complete righť >COMPLETE TASK</a>8inbsp; " + 
"</div>" + 
"</li>"j 

} // for 

jOuery("ul#tasklist").html(listHtml)j 
} // populateTaskList 

Tlie preceding code populates tlie ul#tasklist with the HTIVIL required to display both 
the tasl< name, due date, description, and complete tasl< linl<. Leťs take a peel< at how 
that lool<s. With a couple of tasks in the database, it renders a display like the one 
shown in Figuře 4-9. 
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Figuře 4-9. The All Tasks display with no style applied. What did we do before CSS? 

Iťs pretty obvious that the screen needs to have some style applied, and iťs probably 
appropriate that we do that now before implementing any more JavaScript (otherwise 
we won't be able to tell when something is selected). The following CSS will give us a 
result similar to the mockup: 

ul#tasklist { 
margin: 0; 
padding: 0; 

list-style-type: none; 

} 

ul#tasklist > li { 
padding: 0; 
margin: 0; 
clear: both; 
background: #ececec; 

} 

ul#tasklist > li:nth-child(2n) { 

background: #cccccc; 

} 

ul#tasklist .task-header { 

padding: I9px Opx I7px lOpx; 

} 

ul#tasklist .task-details { 
clear: both; 
background: #333333; 



color: white; 
padding: 8px; 
display: none; 

} 

ul#tasklist .task-details a { 
color: white; 
text-decoration: nonej 
font: bold 0.8em Arial; 

} 

While most of this is common CSS, note the bold CSS3 selector for the list items within 
#tasklist. This selector matches every second list item in the task list, and thus an 
alternativě background color is applied. There are quite a few additional CSS selectors 
available in the CSS3 selectors specification (www.w3.org/TR/css3- 
selectors/#selectors), so iťs weil worth keeping an eye on whaťs going on in that 
space. While we won't go through them in detail here, we wouid definitely encourage 
you to visit the link at the W3C site and experiment with them in your own appíications. 

We also apply some extra styles to make our date look like a nice little calendar: 

ul.calendar { 

-webkit-border-radius: 4px; 
-webkit-box-shadow: O O 2px #333333; 

background: -webkit-gradient(linear, left top, left bottom, color-stop(0.0, 
#F8F8F8), color-stop(l.O, #AAAAAA)); 
margin: 5px 5px 6px 0; 
padding: O 6px; 
list-style-type: none; 

} 

ul.calendar li { 
margin: 0; 
padding: 0; 
text-align: center; 
font-weight: bold; 
font-size: 0.7em; 

} 

ul.calendar li.day { 
font-size: 0.85em; 
padding: ipx 0 0 0; 

} 

With the stylesheet applied, our screen shouid look something like the one in Figuře 4- 
10. 
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Figuře 4-10. With some CSS applied, iťs starting to look the part. 



So we are almost there. We just need to go back and add the required JavaScript to 
toggie the display of the task description and complete the task link: 

function toggleDetailsDisplay(listltem) { 

// slide up any active task details panes 
jOueryC' .task-details") .slideUpO; 

// if the current item is selected, implement a toggie 
if (activeltem == listitem) { 

activeltem = null; 

return; 

} 

// in the current list iteirij toggie the display of the details pane 
jOuery(listltem) .f ind(" .task-details") .slideDownO; 

// update the active item 
activeltem = listitem; 
} // toggleDetailsDisplay 



EXERCISE 4-2: FINISHING OFF THE ALL TASKS SCREEN 



We're going to go on ahead and implement those extensions to the PROWEBAPPS.ViewManager module 
to support automatically adding a Back link for screens other than the application main screen. If you 
wouldn't mind finishing off the All Tasks screen, that wouid be fantastic. 

From here, all that really needs to be done is to implement the complete-task functionality — but that 
shouid be pretty simple given we did it on the main screen. You couid also add some additional CSS to 
show that a task is overdue (as per the mockup). 



Implementing the View Stack 

If you haven't noticed aiready, iťs pretty frustrating that, when we Init a particular screen 
in our application, tine oniy way to get back to the previous screen is to refresh the page. 
This isn't going to cut it, so iťs time to do something about it. 

The first thing that is required will be to implement some kind of view or screen stack. 
We need a mechanism that will allow us to keep track of which screens have preceded 
this one. The best pláce to implement this functionality will be in the switchView priváte 
function in the PROWEBAPPS.ViewManager module. Leťs modify that function now: 

function switchView(oldView, newView) { 
var ii, menu = jOuery("#menu").get(o); 

// if the old view is assigned, then push it onto the stack 
updateViewStack(oldView, newView) ; 

} // switchView 

As you can see, we have added a call to a new function called updateViewStack passing 
through the old and the new view. The implementation of updateViewStack is quite 
simple, and is used to determine whether our movement from the oldView to the 
newView shouid change the statě of the stack. 

function updateViewStack(oldVieWj newView) { 

// first leťs determine if we shouid push onto the stack 
var shouldPush = oldView 8181 ( 
(viewStack.length === O) | | 

(newView 81& (viewStack[viewStack.length - l].id != newView. id)) 

); 

// if we shouid push onto the stack, then do so, otherwise pop 
if (shouldPush) { 

viewStack.push(oldView); 

// if the back action does not exist yet, then create it 
if (! backAction) { 

backAction = new module. ViewAction({ 

label: "Back", 

run: function() { 



subModule.activate(viewStack[viewStacl<.length - l].id); 

} 

}); 

} // if 

} 

else if (oldView SS newView && (viewStack.length > O)) { 

viewStack.popO; 
} // if..else 
} // updateViewStack 

In the preceding code, the shouldPush variable is initialized based on the presence of 
having being passed an oldView, and the view stack being either empty or having the 
last item in the stack being something other than the newView we are transitioning to. If 
we are transitioning back to the view that is the most recent view that was pushed to the 
stack, then it will be popped off as a result. 

With the view stack in pláce, the back action can be used to take the user back to 
screens that they were on previously without needing to be told in each and every oase 
what that screen was. This in turn is going to save a lot of effort coding in the long term. 

NOTE: The backAction ViewAction is initialized in the preceding function as opposed to 
variable definitions of the module (which you can see towards the top of the module definition). 
This is not because I am a massive lazy-loading ^an (not creating variables until they are 
needed), but, rather, it is because of the way I have implemented the module pattern. 

In JavaScript, a variable cannot be referenced until the definition of that variable is complete — 
which is fair enough. If we try to reference the ViewAction class of the PROWEBAPPS module 
(using module. ViewAction), itfails. If we create it later, once the definition is complete, 
everything's fine. 



If you encounter this situation, it may be worth considering refactoring your code to define 
modules/classes that are required in a module definition as a separate, priváte module/class and 
then including it in the exported module by using a simple assignment. 



To make use of our newly created stack, we are going to need to modify the 
getViewActions and getAction priváte functions in the ViewManager module. Here is a 
section of the Viewl^anager module that highiights the required changes: 

ViewManager: (function() { 
var views = {}, 

activeView = null, 
viewStack = [], 
backAction = null; 

function getViewActions (view) { 
var html = ""; 

for (var ii = 0; view && (ii < view.actions.length); ii++) { 
html += "<li>" + view.actions[ii] .getAnchorQ + "</li>"; 
} // for 



// if the view stack is active, then add a back action 

if (viewStack.length > O) { 

html += "<li>" + backAction.getAnchorO + "</li>"; 
} // if 

return htmlj 
} // getViewActions 

function getAction(vieWj actionid) { 

// extract the id portion from the action id 
actionid = actionid. replace(/'^action_(\d+)$/i, 

if (backAction && (backAction.id == actionid)) { 

return backAction; 
} // if 

// find the specified view in the active view and execute it 
for (var ii = 0; ii < view.actions.length; ii++) { 

if (view.actions[ii] .id == actionid) { 
return view.actions[ii]; 

} // if 
} // for 

return nullj 
} // getAction 

})()"" 

You can see that two additional variables have been added for the viewStack and the 
backAction. Additionally, the getViewActions and getAction functions are modified to 
properly handle the back action behavior. In the case of getViewActions, the function 
checks whether the viewStack contains any items, and, if it does, includes the 
backAction in the actions that will be displayed for the current view. The changes to the 
getAction method provide the function with a mechanisnn for providing the backAction 
handler even though it hasn't been explicitly defined. 

One finál plece of the puzzle remains. We require a method in the 
PROWEBAPPS.ViewManager module that will allow us to initiate going back manually: 

ViewManager: (function() { 
var subModule = { 



back: function() { 
if (backAction) { 

backAction . execute() ; 
} // if 



}; 



return subModule; 

})() 



This method will be called in instances where you have completed a screen and need to 
retům the user to the previous screen. For instance, we need to cliange tine function call 
PROWEBAPPS.ViewManager.activate("main") to PROWEBAPPS.ViewManager.bacl<() in our 
submit liandler for the task entry form to mal<e sure the application flows correctly. 

And with that, we are done. IVlore can be done to the application itself to polish it up, but 
there are good bones to worl< with here. There are a number of possible extensions that 
couid be nnade to the application to enhance it from this point, so please feel free to try 
anything that Interests you. 

Summary 

In this chapter, we explored one way of implementing a view manager useful for building 
a multipage web app that operates correctly on an Android device. This included looking 
at different ways of navigating through an application and implementing some 
intelligence to create appropriate navigation controls. 

We also finished having a look at the Web SQL Database API by implementing the code 
required to retrieve items from our database and display them in the app. 

By now, you shouid be relatively comfortable with the JavaScript module pattern, and 
be able to implement it in your own applications if you choose to. 

In the next chapter, we will go through how we can synchronize the data in our To Do 
List with an online data store. This will enable us to create other clients (such as a 
desktop web application) that can view the data we are collecting in our mobile app. 
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Cloud 



In this chapter, we will explore using a variety of hosted (or cloud) services that are 
available to us for synchronizing our tasks from our to-do list with online storage. 
AIthough offline storage is a very handy and powerful feature, we cannot deny the fact 
we are in a connected worid. Data shouid be shared and made available online. To 
achieve this, all the data we are collecting locally has to be synchronized with an online 
solution. 

What you will learn in this chapter is how to use leading-edge technologies, such as 
NoSQL cloud-hosted solutions, which are storage systems that don't rely on the classic 
relational form, and instead provide a new way to deal with storing data. We currently 
have a lot of solutions that encapsulate the complexity of these new technologies for 
you and let you focus on the core development of your application. 

But thaťs not all — using an online storage framework provides a way of hosting your 
mobile web application in the cloud, making your application available for the entire 
worId. While native applications live inside a device, mobile web applications need to be 
hosted. That is, their pages are served from a remote location— a server that 
communicates with the mobile native browser. While you couid host your applications 
on one of the many classic web-hosting providers that are available, in this chapter we 
look at a powerful and affordable alternativě cloud-hosting solution. This solution will 
permit you to host both your storage mechanism and the application itself. 



At present, the options for synchronizing locally stored data with centralized storage in 
the cloud are somewhat limited. This situation is slowly changing, though, and in the 
future we may weil be spoiled for choice. For the purposes of this chapter, however, our 
primary need is something that works weil from the client side, and in particular with 
JavaScript; for that reason, JSON (JavaScript Object Notation) will be the formát we'll 
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use to both transmit and store the data. JSON is also useful because iťs the most 
common data interchange formát (besides XML) in web-based architectures in which 
the Client side relies heavily on JavaScript. Leťs take a look at the requirements for a 
suitable online data synchronization store that will ensure that our offline data will be 
mirrored on the Web (and thus accessible to other people). 

Online Synchronization Store Requirements 

What exactly are we looking for in an online storage solution? A solution that wouid 
serve us weil for a generál synchronization solution will require the following features: 

■ Avoiding a complex and somewhat old-school three-tier architecture 
(front end, back end, and database) 

■ Some flavor of user authentication 

■ A supporting JavaScript library that makes synchronizing data stored 
on the device a snap 

Additionally, given that we want to focus on giving users of our application the best 
experience possible, our online storage solution shouldn't take another whole 
person/team to create or maintain. It shouid be both simple and scalable. 

Bearing the requirement of simplicity in mind, we will explore the features just outlined in 
a little more depth. 

Avoiding a Tliree-Tier Arclíitecture 

Classic web applications are based on three-tier architecture, made up of: 

■ A front-end layer, containing the HTML pages, styles, and other assets 

■ A back-end layer, hosted by an application server (such as Tomcat or 
JBoss for enterprise Java solutions, or IIS for .NET applications) 

■ A database provider, such as MySQL, Oracle, or Microsoft SQL Server 

This kind of architecture requires mastering at least three different kinds of development 
skilis: front-end, server-side, and database skills. This is far beyond the scope of this 
book, as we want to put the focus on building web applications— especially on the front- 
end aspects. Furthermore, modem frameworks allow us to abstract much of this 
formerly problematic business logic and storage. 

User Autlientication 

Our mobile application as we have built it now works very weil for a user running it from 
a single device. Having all the Information contained within storage on a single device, 
however, is not a great solution. If instead that Information is going to be stored on the 



Internet sonnewhere, we need some identity information attaclied to it so we can retrieve 
it from a second or tinird device. 

Because we are building a web-based application, not a native application, we are not 
able to use the unique IMEI (International Mobile Equipment Identity) number of the 
device, or any other low-level infornnation. This is because nnobile web browsers have no 
access to this information. Fortunately, there are many options available on the web side 
to manage your identity. That identity couid be many things— an OpenID (see 
http : //openid . net), a Google account, or a Twitter account, to name but a few. It 
shouid, however, not be a new account that people have to create for this particular 
application and then again for another application, as this does not constitute a reusable 
(and thus efficient) solution. 

A JavaScript Synchronization Library 

Ideally, we are looking for a solution that can take our locally stored data and do some 
convention-based synchronization processing to push our data in the cloud. Once this 
data is online, we wouid then be able to use it from a desktop application, or maybe a 
tablet running either Android or Chromé. 

At this stage, offerings in this space are especially hard to find, as cross-platform web apps 
are pretty new on most people's radars. Another option is to write your own synchronization 
library. This shouldn't be too difficult, as our needs are quite simple, and you have aiready 
seen in the previous chapter how to communicate with an offline database. 

Possible Synchronization Solutions 

One solution that does a good job of covering our needs is jsonengine (see 
http://code.google.eom/p/jsonengine). The following are some of its most valuable 
features: 

■ It runs on Google App Engine (a cloud-based solution). 

■ It requires no back-end scripting. 

■ It provides identity management using the Google account mechanism 
and OpenID. 

■ Besides being a data storage solution, iťs also possible to host and 
serve the application code from within jsonengine itself. 

As the name suggests, jsonengine uses the JSON formát to store its data. This is useful, 
since our application is heavily based on JavaScript, and iťs easy to manipulate JSON 
objects using the JS0N2 library. 

Additionally, jsonengine provides a robust mechanism for inserting data via a REST 
(http : //en . wikipedia . org/wiki/Representational_State_Transf er) API. The API 
endpoints provide the ability to read, insert, update, and delete data using standard 
HTTP methods (GET, POST, PUT and DELETE respectively). 




Getting Started with Google App Engine 

A jsonengine instance is best hosted on Google App Engine 
(http://appengine.google.com/), wliicli deserves a sliort introduction. Google App 
Engine is Google's cloud-computing technology. It virtualizes web applications across 
multiple servers and data centers. In simple ternns, tínat means tínat your appíication is 
not running in one singíe pínysicaí pláce {Wke a data center in Silicon Valíey), but is 
repíicated alí around the worid using Google's impressive data center coverage. 

Googíe App Engine is a Platform-as-a-Service (PaaS) soíution, and differs fronn the other 
cloud-computing services (such as Annazon Web Services). The nnain difference is that 
Googíe App Engine provides a connplete set of services and tools based on conventions 
rather than configuration, which aílows applications to be depíoyed very quicl^ly. Another 
advantage of Google App Engine is its pricing model — iťs free up to a certain íevel of 
used resources. 

I NOTE: PaaS is íií<e any other type of hosting service, except that, instead of providing you with 
' blank, "wiidcard" server, it offers a predefined set of services and hardware solutions. It 

encapsulates a lot of complexity and configuration tweaks for you. The catch is that you'll have 
I less freedom, and you'll have to follow the solution provider's guidelines. 

So, before you can use jsonengine, you have to set up Google App Engine. The first 
thing you have to do is downioad the Google App Engine framewori<, so you can test 
and deploy your appíication locally before putting it into the cloud. Google App Engine 
proposes two different kinds of framework: 

■ A Python-based SDK 

■ A Java-based SDK 

As jsonengine is based on Java, we are going to use the Java-based version. Don't 
worry if you don't have any knowledge about Java— it won't be necessary. We simply 
need to deploy jsonengine, so you won't have to do anything to configure or implement 
it. 

Leťs start by installing Google App Engine. First, downioad the binaries, which you can 
find here: 

http : //code .google. com/appengine/downloads . html 
Then follow the installation instructions here: 

http://code.google.com/appengine/docs/java/gettingstarted/installing.html 

An additional useful guide for installing the App Engine SDK can be found on the 
jsonengine site: 

http://co de. google. com/p/ jsonengine/ wiki/HowToInstall 




Deploying jsonengine Locally 



Deploying a jsonengine instance is very easy: just downioad tlie provided WAR arcliive 
and deploy it using tlie following Google App Engine command: 

devappserver location/to/you/war/folder 

TIlis will start the Google App Engine server locally, open your favorite browser, and go 
to http ://localhost:8080/samples/bbs. html. You shouid now be able to see the 
jsonengine's sample application. 

Thaťs all! Now that you have an up-and-running, ultra-scalable online storage solution, 
we can go back to our to-do application to start implementing the synchronization 
process. 

Since jsonengine is a web application, not just a storage solution, it can serve web 
content, making it ideál for the mobile web application we're building. All the code we've 
implemented (HTML, JavaScript, and CSS) can be hosted inside jsonengine's instance. 

Take a look at the jsonengine's distribution. It has a war folder containing a classic web 
application structure (CSS, JS, etc). If you have all your resources inside the right 
folders, with a single command from the App Engine SDK, you can actually deploy your 
application— which is pretty neat. When you deploy your application, the war folder is 
packaged in a WAR archive. (A WAR archive is simply the enterprise version of a JAR 
(Java archive formát); it functions just like a ZIP file.) 

Leťs perform a quick test to ensure that jsonengine does indeed serve web assets in 
addition to JSON data. Take the sample code from Chapter 4 and paste it in your war 
folder. This shouid result in the following folder structure: 

DSONEngine- 
|- war- 
|- css- 

|- proul.css 

I- 

|- jquery-l.4.2.[nin. js 
|- jquery . validate. js 
I- ]son2.js 
|- prowebapps. js 
|- snippets- 
I- 04- 

- todolist.html 

- todolist.css 

- todolist.js 

Browse to http ://localhost:8080/snippets/04/todolist. html, and you will see your 
application running. 

Since we're building a mobile web application, you shouid also try it on the Android 
emulátor. As discussed in Chapter 1 , the Android emulátor is unable to communicate 
with a Webserver on your machine via the localhost address. As such, we will need to 
instruct the AppEngine development server to bind to other network addresses on our 
machine (by default, the Google App Engine local server binds to the localhost address). 
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Fortunately, though, the dev_appserver command comes with an option parameter to 
make the server listen on all the IPs (0.0.0.0) of your local machine. 

Stop your server and restart it by adding the following parameter -a o.o.o.o right after 
your command and before the path to your war folder. Once you have done this, you will 
be able to access the application from the emulátor or mobile device by using the IP of 
your local machine. 



NOTE: If you have Mongoose running in the background, the AppEngine development server 
not be able to bind to the alternativě address. In this case, simply close down the Mongoose 
server and then start the AppEngine dev server again. 



m will ■ 



At the end of this chapter, you'll see how to deploy the application on the cloud; iťs not 
very complicated and it can be done in one single command. The deployed online 
application will have the exact same behavior as on your local server— there is nothing 
to configure and iťs definitively a huge time-saver. 



Choosing a Suitable Synchronization Mode 

Ideally, data synchronization is bidirectional, which means that, for example, systém A 
creates/updates records that will be reflected on systém B, which can also 
update/create data. However, that brings a lot of data integrity issues. For example, 
what if systém A is updating a record that systém B is deleting? With a legacy storage 
systém like Oracle or MySQL, you can use locks, rollbacks, and other similar features to 
deal with these kinds of issues. But now we are using a quite different and innovative 
approach, and to keep things on a reasonable easy level we will choose a simple but still 
powerful synchronization mode. 

We will use a one-way synchronization, in which the offline database will be the master 
and the online storage will be the slavě. That means that each new record will aiways be 
stored initially in the offline database, and will be synchronized with the online storage 
oniy after the user decides to do so. Inserting new records directly into jsonengine will 
be impossible. 

To illustrate this, leťs imagine the following use case: our to-do web application has 
become popular and is being used by a famous scientist who's collecting data in the 
middle of the jungle. All day long, the data is stored offline, but, when the scientist 
returns to his headquarters at the end of the day, he wants to share his collected 
Information with the other scientists working in the main office in Amsterdam. His 
colleagues have read-oniy permissions, but there are also batoh processes that will 
output very interesting statistics for all scientists around the worid. 



Sending Your Offline Data to jsonengine 



As jsonengine expects input in JSON formát, we have to convert our offline SQL data to 
JSON formát. The globál flow is quite simple: 

1. Select all the offline records. 

2. Parse them to JSON formát. 

3. Send them to jsonengine. 

Selecting all the database records is something we have aiready done before, so we can 
copy and paste an existing function, clean it up, add some JSON conversion goodness, 
and finally send the data to our online storage service, as follows: 

function synchronizeOnline(callback) { 
db.transaction(function(transaction) { 
transaction.executeSql( 

"SELECT rowid as id, * FROM task 
[], 

function (transaction, results) { 
var tasksSynchronized = 0; 

// initialise an array to hold the tasks 
// read each of the rows from the db, and create tasks 
for (var ii = 0; ii < results. rows. length; ii++) { 
var task = new module. Task(results. rows. item(ii)), 
taskDson = DSON.stringify(task); 

$.post("/_je/tasks", {_doc:task3son,_docId:task.id}, function() { 
// once the post has completed, increment the counter 
tasksSynchronized += l; 

// and check to see if we have finished the syne operation 
if (callback && (tasksSynchronized === results. rows. length)) { 

callback(tasksSynchronized, true); 
} // if 

}); 

} // for 

// fire the callback and provide Information on the number 
// of tasks that were updated 
if (callback) { 

callback(results . rows . length, falše) ; 
} // if 

} 

); 

}); 

} 

Leťs focus on the for loop, where the interesting stuff happens. Firstly, we use the 
JSON library to serialize a Task object that we have retrieved from the database to a 
JSON string. Next, we use the jOuery post function to send that serialized data (using a 
POST request) to jsonengine for storage. 




You can see that our post call takés three arguments: 

■ The first argument is the uri that we are making the POST request to. 
In this oase, our storage URL is the same as our application; we just 
prefix it with _je (for "JSON storage")— this is simply a jsonengine 
convention. 

■ Our next argument contains the data that we are sending through the 
jsonengine. For jsonengine to be able to save our data effectively, it 
needs two things: 

■ A document (_doc)— this is the data that is going to be stored. 

■ A document id (_docId)— the unique key of our document that we 
are storing. As jsonengine is smart enough to detect whether the 
provided _docld aiready exists, and will either create a new 
record or update the existing record. 

■ Finally, we supply a success callback for the post function and this is 
called once the request has been successfully completed. 

What is happening here? First, we're using jOuery's post function. This is one of 
jOuery's most powerful functions when we have to deal with network communication. 
This function will perform a HTTP POST request, and of course we pass an array of 
parameters: ("/_je/tasks", {_doc:taskDson,_docId:task.id}j success callback). 

The first parameter is the URL to which we are posting our request. In this oase, our 
storage URL will be the same as our application; we just prefix it with _js (for "JSON 
storage")— this is simply a jsonengine convention. 

The second parameter, {_doc:task3son,_docId:task.id}, is more jsonengine specific. 
Iťs a nested parameter's map. _doc defines the name of our storage record, and it can 
be compared to a database table name. The value we provide is the freshly JSON- 
converted string; in jsonengine terms, iťs called the JSON document. Then, _docId 
represents the unique key of our record. As you can see, we are using the index of our 
for loop because iťs the same index as the ID of each of the offline task's entries. 

I 

NOTE: Where does jsonengine store the submitted JSON strings? Iťs using Google App Engine's 
data store. As Google's online storage solution, Google App Engine takés care of all the 
distribution, replication, and load balancing of data. In fact, jsonengine is just an abstraction layer 
above the data store to perform the storage of JSON documents transparently. ^ 



Updating the User Interface for Online 
Synchronization 

We have now enhanced our custom library with a function to synchronize the offline 
data with an online storage solution, but in order to test it we need to add some user 
interaction. Therefore, we have to work on our user interface layer and see how we can 
bind a back-end function to a visually interactive action. Leťs add a button called 
"Synchronize" to the main screen: 

<ul class="buttons"> 

<li><a class="changeview" href ="#alltasks">Show All Tasks</a></li> 
<li><a class="changeview" href="#add">Add New</a></li> 

<li class="changeview"><a href="#" class="synchronize">Synchronize</a></li> 
</ul> 

Now we have to bind the click event to our new synchronizeOnline() function: 

activateMain: function() { 

TODOLIST. Storage. getMostImportantTask(function(task) { 
if (task) { 

// the no tasks message may be displayed, so remove it 
jOuery("#main .notasks") .remove(); 

// update the task details 
showTaskDetails("#[nain .task", task); 

// attach a click handler to the complete task button 
jOuery("#main .task-co[nplete").unbind().click(function() { 
jOuery("#main .task") .slideUp(); 

// mark the task as complete 
task.completeO; 

// save the task back to storage 

TODOLIST. Storage. saveTask (task, module. activateMain); 

}); 

jOuery("#main . synchronize"). unbind().click(function() { 
TODOLIST. Storage . synchronizeTasks ( ) ; 

}); 

} 

else { 

jOuery("#main .notasks") .remove(); 

jOuery("#main .task") .slideUp() .after("<p class=' notasks '>You have no tasks 
to complete</p>"); 
} 

}); 

} 

Then we simply exposé the synchronizeOnline function through the Storage 
submodule as the synchronizeTasks function: 
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Storage: (function() { 

var subModule = { 

synchronizeTasks : synchronizeOnline, 

}; 

return subModule; 

})() 

Refresh your application, and you will see your updated user interface, as shown in 
Figuře 5-1. 
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Figuře 5-1 . Adding a Synchronize button 

We can now just click the Synchronize button, and all the offline data will be flushed into 
a modem and ultra-scalable JSON storage systém! Thaťs nice, but so far we don't have 
any feedback about this process— it happens all under the hood. To remedy that, leťs 
display an info banner once the synchronization process is done. 

First, we add an "info" div element just before the button stack; 



<div id="info"></div> 
<ul class="buttons"> 

<li><a class="changeview" href="#alltasks">Show All Tasks</a></li> 
<li><a class="changeview" href="#add">Add New</a></li> 

<li class="changeview"><a href="#" class="synchronize">synchronize</a></li> 
</ul> 



Then add some styling for this div: 

#info { 

margin: 8px 6px 2px 6px; 
padding: 6px I4px; 

background: -webkit-gradient(linear, left topj left bottom, color-stop(0.0, 
#71D90F), color-stop(0.7, #529E0B)); 
-webkit-border-radius: 4px; 
color: white; 
display: none; 

} 

Notice the display: none attribute, which ensures that the div won't be visible until we 
explicitly want it to be displayed. 

To display the notification message, leťs make a change to our activateMain function 
to show some information once the synchronization process has been initiated: 

activateMain: function() { 

TODOLIST.Storage.getMostImportantTask(function(task) { 
if (task) { 

jOuery("#main .synchronize") .unbind() .click(function() { 

TODOLIST.Storage.synchronizeTasks(function(updateCount) { 
$("#info") 

.html("Completed : " + updateCount + " task(s) have been 



synchronized !") 

}); 

}); 

} 



.show(); 



}); 

} 

All we're doing here is updating the info div HTML. Now, when the synchronization 
process completes, the info banner will be displayed, as shown in Figuře 5-2. 
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Figuře 5-2. Visual synchronization feedback 

Now that we're sure our synchronization process is worl<ing, we need a client interface 
that will read the data from our online storage solution. 

Making a Desktop Interface 

One of the benefits of building a web-based application is that you can easily provide 
access to your data in different web-based formats— for example, tablet devices and 
more standard desktop browsers. First, leťs focus on the latter and see how we can 
connect our storage solution to a "regular" desktop web application. 

Creating a desktop interface from an existing mobile interface is far simpler than trying 
to create a mobile interface from an existing desktop web application. To see evidence 
of this, look at the way the various mobile application interfaces have affected the user 
interfaces of their various big brothers. The recent revisions to the Twitter web interface 
are an example of how mobile user interface paradigms can affect desktop interfaces to 
create a better user experience (see http://twitter.com). 

As we have one-way synchronization oniy, the desktop application will be read-oniy 
(and, because building a desktop interface is not really in the scope of this book, we'll 
keep it minimal). If we go back to the example of our scientist collecting data, consider 
the desktop application as a reporting tool for his colleagues all around the worid who 
want to keep informed about his latest findings. 

What you'll learn in this section is that building a mobile web application relying on 
robust and standard web technologies allows you to extend its features to other web- 
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based engines, and especially to a desktop web interface, like the browser you use on 
your laptop or desktop systém. 

The first thing we have to do is to retrieve the data we stored on our cloud-based 
storage solution. 

Querying a jsonengine Instance 

You've aiready seen how easy it is to insert data using the REST API. Likewise, making a 
query will also be done through the REST API, using the HTTP GET method. First, we 
have to create a new HTML page— leťs call it todolist-readonly.html. 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
" http : //www . w3 . org/TR/html4/loose . dtd " > 
<html> 
<head> 

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 
<title>Tasks page</title> 

<link rel="stylesheet" media="screen" href ="todolist-readonly.css" /> 
<script type="text/javascript" src=" . ./. ./js/jquery-l.4.2.min. js"></script> 
<script type="text/javascript"> 
// get all the posts and show them 
$(function() { 

$.get("/_je/tasks", { sort: "_createdAt.desc" }, function (result) { 
var rowsHtml = ' ' ; 

for (var ii = 0; ii < result. length; ii++) { 
rowsHtml += '<tr>' + 

'<td>' + result[ii] .name + '</td>' + 
'<td>' + resultfii] .description + '</td>' + 
'<td>' + resultfii] .due + '</td>' + 
'</tr>'; 
} // for 

$( ' #taskTable tbody ' ) . html(rowsHtml) ; 

}); 

}); 

</script> 

</head> 

<body> 

<hl>Current tasks stored in jsonengine</hl> 
<table id="taskTable"> 
<thead> 
<tr> 

<th>Name</th> 
<th>Description</th> 
<th>Due</th> 
</tr> 
</thead> 
<tbody /> 
</table> 
</body> 
</html> 



The interesting part here is the JavaScript function that is called when the page is 
loaded. We are using jQuery's get function— the syntax is almost the same as the post 
function, but we are now passing sorting parameters. The result is an array of JSON 
documents. A JSON document is a JSON string representation of a Tasl< instance. We 
just have to iterate through the array and update a HTIVIL table to add a new row. 

In this particular instance, we are first collecting all the new rows in a string and then 
replacing the body of the table (tbody) using a single call using the jOuery html function. 
While we couid just as easily have appended each row as we found it, we increase the 
speed of our application by trying to do updates to the HTML as few times as possible. 
While iťs not something that you wouid notice in a small page like this, it is a good hábit 
to get into. 

With the HTML page complete, we will also add some very basic styling to the 
todolist-readonly .css stylesheet: 

table, td { 

border: ipx solid #666665; 
width: 100%; 



td { 

width: 33%; 
padding: 2px; 

} 

Then navigate to your freshly made page, and you shouid see something like Figuře 5-3. 
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As you can see, all the data inside the offline database is now available online— at least 
on the server, that is; we haven't yet uploaded our application to the cloud. Before doing 
that, we have to add some security to the storage solution; if we leave it as it is, 
everybody will have access to the desktop web page. Fortunately, jsonengine comes 
with a security admin page where you can set the access level for your storage 
documents, as shown in Figuře 5-4. 
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Figuře 5-4. The jsonengine security admin page 



Here, we can add our JSON "tasks" document and set the read level to "protected," so 
that users will oniy be able to view the data if they are connected with their Google or 
OpenID accounts. 



Deploying Your Application on tlie Cioud 

OK, iťs time to go live so that the whole worid will be able to use your mobile 
application. But first you will need a Google account (or Gmail account). Once you have 
that, you can access Google App Engine by logging in at 

https://appengine.google.coni. Fronn there, you can create a new application, and 
choose an application identifier— which will also be the URL to access your app— and a 
title. Before you upload our application, you must be sure that the application identifier 



matches the one that is defined in your local application. To do this, open the war/web- 
ing/appengine-web.xml file and check this line: 

<application>jsonengine</application> 

Replace jsonengine with the application ID you chose just before. Now youVe ready to 
deploy your application— go to the bin folder of your Google App Engine SDK and type 
the following command (on Windows): 

appcfg.cmd update location/to/you/war/folder 

On the Mac and Linux, type the following: 

appcfg.sh update location/to/you/war/folder 

Enter your Google username and password at the prompts. If the upload process is 
successful, you will see the message "Update completed successfully." Thaťs it! Our 
application is in the cloud — navigate to your page: http://my-app- 
id.appspot.com/snippets/05/todolist-readonly.html. 

Summary 

We have achieved some interesting things so far: we have a mobile web application with 
powerful features that can store data offline and synchronize it with an online 
environment. Synchronizing offline data for a mobile app with a powerful online storage 
mechanism is a very new and innovative concept. 

What we need now are some features to compete with native applications. In the next 
chapter, we'll add some tasty user interface elements and deal with offline conditions. 




Competing with Native 
Apps 

Iťs quite impressive that we can produce powerful and scalable mobile web 
applications just using HTML, CSS, and JavaScript. However, so far we haven't 
achieved tine lool< and feel tínat we wouid with a native application. Also, if our Internet 
connection goes down, our application will probably stop working, despite the fact that 
we're using a local database. 

In this chapter, you will learn how to go a step further in polishing your web app, first by 
adding user interface enhancements. We'll use CSS3's amazing animation and transition 
capabilities, and we'll also use robust and popular JavaScript libraries. Next, we'll add 
geolocation and offline support using the latest HTML5 specifications and the Chromé 
browser. At the end of this chapter, we will have a fully standalone application that will 
be very similar to a native application. 

Adding Lightweight Animations and Native-Like 
Layouts 

One of the big differences between native and web applications is that web applications 
often lack the great-looking user interfaces that native apps can offer. The good news is 
that technologies like HTML5, CSS3, and JavaScript can now offer solutions that 
compete with native technologies— for example, providing native browser animation 
features and ensuring that specific visual elements have a fixed position, such as a top 
bar menu. 

One of these new technologies, CSS3, adds a lot of improvements, including shadows, 
rotations, and gradients. But for this part we will focus on two very interesting features: 
CSS transitions and CSS animations. 
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Adding a Simple Loading Spinner 

In the previous chapter, we implemented an online synchronization function. The oniy 
visual feedback we had was an info banner telling us the process was successful. But 
what about during the process itself? For exannple, if we have thousands of records to 
synchronize, it will take some time before this process is done. In this oase, it wouid be 
nice to have some visual feedback during the synchronization, like a loading spinner. 

In the old-fashioned way, you wouId use a semitransparent animated GIF and control it 
with sonne JavaScript. The downside of this approach is that it requires an extra 
resource with a limited number of frames (to keep the image slze as small as possible), 
which reduces the smoothness of the animation; and, because the image is 
semitransparent with its hardcoded foreground and background color, you also add a 
dependency to the application's color chart. If you decide to change the background 
color of your application, you also have to generate your animated GIF again. 

For these reasons, we won't use an image; instead, we'll "draw" and animate the 
spinner using CSS3 animations and transitions. The spinner will consist of 12 bars 
rotating around an axis and fading out. Leťs first define the main spinner style: 

div. spinner { 

position: absolute; 
top: 50%; 
left:70%; 

margin: -lOOpx O O -lOOpx; 
height: 54px; 
width: 54px; 
text-indent: 250px; 
white-space: nowrap; 
overflow: hidde; 

} 

Then we define the inner div style. Here, we set the common styles that will be shared 
by all the bars. Basically, we create a bar by styling a div, playing with the corner rádius 
and shadow properties. We also attach an animation to a bar— a fade animation that will 
be defined later. 

div. spinner div { 
width: 12%; 
height: 26%; 
background: #000; 
position: absolute; 
left: 50%; 
top: 50%; 
opacity: 0; 

-webkit-animation: fade is linear infinite; 
-webkit-border-radius: 50px; 
-webkit-box-shadow: O O 3px rgba(0,0,0,0.2); 

} 

Finally, we define the 12 bars that will be used in the animation, increasing the rotation 
angle for each of them by 30 degrees using the -webkit-transform:rotate attribute. The 
fade effect, combined with a different start delay using the -webkit-animation-delay 
attribute for each bar, will create the illusion of a rotation effect. 




div.spinner div.barl { 

-webkit 
-webkit 



transform:rotate(Odeg) translate(0, -1A2%); 
animation-delay : Os; 



} 

div.spinner div.bar2 { 



-webkit 
-webkit 



transform:rotate(30deg) translate(o, -142%); 
animation-delay: 0.9l76s; 



} 



[..] 

div.spinner div.barl2 { 

-webkit 
-webkit 



transform:rotate(330deg) translate(0, -142%); 
animation-delay: -0.0833s; 



} 



We also define our fade animation: 

|5)-webkit-keyframes fade { 
from {opacity: l;} 
to {opacity: 0.25;} 

} 

Before we try out the spinner, leťs introduce some new CSS3 selectors: 

■ -webkit-animation: Defines the name of your animation, winicin will be 
declared in a separate style blocl< starting witli @-webkit-keyframes. 
Notice tlie values tínat follow tlie name of tlie animation: we liave a 
duration value, a transition-timing function that defines liow tlie 
animation sliouid proceed over tine duration (Inere we are using a linear 
function, but tinere are a lot of different options— ease-in, ease-out, 
etc), and finally a value defining the animation's frequency (the 
animation will run infinitely in our oase). 

■ -webkit-transform: Can transform any HTML element. Its possible 
values are translate, rotate, and scale. Notice that you can chain 
transform values like we did in the previous code sample— we first 
rotate the div and translate it to the upper-left corner to make it rotate 
around an axis. 

■ -webkit-animation-delay-count: Defines the delay before your 
animation starts. This is useful when you want to chain a lot of 
different animations, like our 12 bars. 

1 

NOTE: A linear transition function will time your animation equally over the duration you provide; I 
for example, if you are moving an image by 200 pixels with a duration of 2 seconds, after 1 I 
second your image will have moved by 1 00 pixels. But maybe there are situations where you W^Ě 
want to have another type of timing, like rotating an image vary slowly in the beginning and 
finishing with a fast rotation. ^^^^H 

To be able to test our loading spinner, we have to add a div containing all the bars' divs 
on the main page: 
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<div id="spinner"> 

<div class="barl"></div> 
<div class="bar2"></div> 
<div class="bar3"></div> 
<div class="bar4"></div> 
<div class="bar5"></div> 
<div class="bar6"></div> 
<div class="bar7"></div> 
<div class="bar8"></div> 
<div class="bar9"></div> 
<div class="barlO"></div> 
<div class="barll"></div> 
<div class="barl2"></div> 

</div> 

Refresh your application and you will see the loading spinner, as shown in Figuře 6-1. 
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Figuře 6-1 . Displaying a loading spinner on the main view 



This is a good first step, but we oniy want to see tlie spinner when we are 
synclironizing — not all the time, even if iťs a beautiful spinner. It shouid appear at the 
moment we press the Synchronize button and disappear when we show the info banner 
displaying that the process was successful. To do this, we update the main spinner style 
with display :none; and we control the container visibility with some JavaScript. 

The best pláce to hook in is probably the synchronizeOnline function; we set the 
visibility of the spinner container to true when entering the function and revert it to falše 
just before we exit the function: 
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function synchronizeOnline () { 

$("spinner") . .show(); 
[...] 

$("spinner"). .hide(); 

} 

Thaťs all we have to do. Notice the handy jQuery's hide and show functions, which 
encapsulate some CSS manipulation for us. 

Adding Scrollable Content 

As our tasks list continues to grow, it will end up not fitting on the screen anymore. Of 
course, the browser will natively insert a vertical scrollbar, but, when you scroll down, 
your top bar containing the title will disappear. Remember, we are competing with native 
apps, and this kind of behavior is not exactly what we are hoping for. 

Fortunately, there is a JavaScript library that will help us fix this visual problém: iScroll 
(http://cubiq.org/iscroll). This piece of JavaScript can make a particular container 
scrollable. Once your script is imported into your page, you just have to declare a 
scrollable instance variable: myScroll = new iScroll('scroller');. 

Leťs see how we can integrate this in our application. The oniy part where we need this 
is in the All Tasks screen, so leťs see how we can refactor this element: 

<div id="alltasks" class="view"> 
<hl class="fancy">All Tasks</hl> 
<div id="wrapper"> 

<div id="scroller"> 

<ul id="tasklist"></ul> 

</div> 
<div> 

</div> 

Notice here that the scrollable div is wrapped by another div that will have a fixed size. 
Here is the CSS of the wrapper div: 

#wrapper { 

position:relative; 
z-index: 1; 
width:auto; 
overflow:hidden; 

} 

You may wonder why we are not setting the height, since the wrapping container must 
have a fixed height. Thaťs because we will set the height programmatically, ensuring it 
will be correct whatever the screen size is. That brings us to the JavaScript part— we 
just have to fire up an iScroll instance and set the height. We put that in the ready 
function because it has to be initialized when the page loads. 

$(document) .ready(function() { 
[..] 

myScroll = new iScroll('scroller' , {desktopCompatibility:true}); 
var wrapperH = window. innerHeight - 35; 

docu[nent.getElementById( 'wrapper '). style. height = wrapperH; 

}); 
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Be sure you have enough tasks in your application and browse to All Tasks view, as 
shown in Figuře 6-2; you shouid now be able to scroll your tasl<s without the title bar 
scrolling along. 
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Figuře 6-2. Adding a scrollable div with fixed header and footer 



Sprucing Up the Action Bar 

We are getting pretty close to a native application look and feel, but the action bar at tine 
bottom couid be a bit nicer, and shouid also be present on the start page; that will 
reinforce the feeling that we are staying on the same page whatever we do. 

Leťs start by adding the action bar on the main page by tweaking the ViewManager: 

// define the alltasks view 

PROWEBAPPS. ViewManager. define({ 
id: "main", 
actions: [ 

new PROWEBAPPS. ChangeViewAction({ 
target: "alltasks", 
label: "All tasks", 
className: "alltasks" 
}), 

new PROWEBAPPS. ChangeViewAction({ 
target: "add", 
label: "Add", 
className: "add" 

}), 

new PROWEBAPPS. ViewAction({ 
target: "synchronize", 
label: "Synchronize", 



className: "synchronize" 
}) 

] 

}); 

The refactoring is pretty simple: the action bar is rendered when the action stack is not 
null; also, instead of defining an action stack for the alltasks view, we define an action 
stack for the main view. Notice that the synchronize action is using ViewAction, not 
ChangeViewAction, because we don't want to switch to another view when we activate 
this action. As you can see, we also introduce a new property— className. Here iťs oniy 
relevant for the synchronize action because the click handler function is bound to the 
elemenťs class name. 

The action bar is not rendered on the main view; we can remove all the buttons as they 
have moved to the action bar. The actions are rendered now like old-fashioned web 
links; we can easily style them so that they appear as buttons. 

ul#menu li a { 

display: block; 

background: -webkit-gradient(linear, left top^ left bottom, color-stop(0.0, 
#b3b3b3), color-stop(0.4, #666666), color-stop(l.O, #333333));; 
color: white; 
text-decoration: none; 
padding: 8px; 
text-align: center; 

-webkit-box-shadow: O 2px 2px #333333; 
-webkit-border-radius: 6px; 

} 

Refresh your page and you shouid see our native-like application, as shown in Figuře 6-3. 
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Figuře 6-3. Restyling the action bar 



CHAPTER 6: Competing with Native Apps 



Making Your Application Location-Aware 

One of the things that make mobile applications unique is that they can detect and make 
use of your current physical location. One of the most famous applications that use this 
information is foursquare, an app that allows people to "check into" particular places 
and share this information with others. 

For a long time, these kinds of features were oniy possible with native applications, 
which had access to lower-level hardware such as the GPS sensor. Again, W3C's 
HTML5 team came up with a revolutionary proposal by allowing the browser to access 
the GPS of your device and exposé it through a JavaScript library. In other words, 
mobile web applications can now be location-aware, thus bridging a huge gap between 
native and web-based applications. This topič will be centrál to the discussion in this 
chapter. 



L 



NOTE: For a long time, mobile web applications didn't have access to low-level hardware, such 
as the camera or the GPS sensor. However, things are changing — the browser is a native 
application and has access to low-level hardware APls, and can exposé them to web applications 
by providing extra JavaScript functions. For the moment, onIy a few low-level APls are exposed 
(e.g., Geolocation and DeviceOrientation events) Camera and contact list access are still 
unavailable, but with the growing popularity of mobile web applications, iťs likely that such 
access will be added in the future. 
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The W3C Geolocation API Specification 

The entry point of the W3C Geolocation API is a simple JavaScript function with its 
callback function: 

navigátor. geolocat ion. getCurrentPosition(showMap); 

function showMap(position) { 

// handle position variable 

} 

This will be sufficient to retrieve our current location; the callback function showMap takés 
a position parameter that contains all the information we need to make our application 
location-aware. Tables 6-1 and 6-2 outline the Position object and its associated 
Coordinates object. 

Table 6-1. The Position Object 



Property Name 



Type 



coords 
titnestamp 



Coordinates 
DOMTimestamp 



Table 6-2. The Coordinates Object 



Property Name 



Type 



longitude 



double 



latitude 



double 



altitude 



double 



accuracy 



double 



altitudeAccuracy 



double 



heading 



double 



speed 



double 



That may seem like a lot of information, but for now we are really interested in oniy two 
attributes: longitude and latitude, which will be enough to determine our geolocation 

and eventually display it on a map. So, position.coords. longitude and 
position.coords. latitude are the properties we want to handle. 

Leťs take advantage of the local storage feature discussed previously, and store our 
position on the browser side when we start our application so we will be able to access 

this information whenever we want. First, we have to retrieve our location — leťs do that 
inside the ready function and store the location in the callback function: 

$(document) .ready(function() { 



localStorage . setltem( ' longitude ' , position . coords . longitude) ; 

localStorage . setltem( ' latitude ' , position . coords . latitude) ; 

$("#geolocation") 
.html("Your position : " + position. coords. latitude + 
","+ position . coords . longitude) 
.css("display"/'block"); 



Notice that at the end of the function we manipulate the geolocation DOM element; this 
will be an information banner displayed on the main screen that shows our current 
position. So we also add a geolocation div element on the main screen: 

<div id="geolocation"> </div> 
Next, we apply some styling: 

#geolocation { 

margin: 8px 6px 2px 6px; 
padding: 6px I4px; 




background: -webkit-gradient(linear, left top, left bottom, color-stop(0.0, 
#71D90F), color-stop(0.7, #529EOB)); 
-webkit-border-radius: 4px; 
color: white; 
display: none; 

} 

Start your application, and a pop-up will ask permission to share your location. After 
accepting, you shouid see the screen shown in Figuře 6-4. 
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Figuře 6-4. Displaying your geolocation 



Now that we are sure our location has been retrieved and stored offline, we can enhance 
our Task object with the new data. This will be very simple— we just have to change the 
structure of our Task table by adding two columns: longitude and latitude. And once 
we save a new task, we just have to retrieve the geoinformation from our local storage. 
Leťs start by updating our database structure: 

// open/create a database for the application (expected size ~ lOOK) 
var db = null; 

try { 

db = openDatabase("todolist"j "1.2", "To Do List Database", 100 * 1024); 

// check that we have the required tables created 
db.transaction(function(transaction) { 
transaction.executeSql( 

"CREATE TABLE IF NOT EXISTS task(" + 

" name TEXT NOT NULL, " + 

" description TEXT, " + 

" due DATETIME, " + 

" completed DATETIME, " + 
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" longitude 

REAL, " + 

" latitude 

REAL";"); 

}); 

} 

catch (e) { 

db = openDatabase("todolist"j "l.l", "To Do List Database", 100 * 1024); 

// check that we have the required tables created 
db.transaction(function(transaction) { 
transaction.executeSql( 

"CREATE TABLE IF NOT EXISTS task(" + 

" name TEXT NOT NULL, " + 

" description TEXT, " + 

" due DATETIME, " + 

" completed DATETIME);"); 

}); 

db.changeVersion("l. 1", "1.2", f unction(transaction) { 

transaction.executeSql("ALTER TABLE task ADD longitude REAL;"); 

transaction.executeSql(" ALTER 

TABLE task ADD latitude REAL;"); 

}); 

} 

This shouid remind you of what we did in Chapter 3 to update an existing database. 
Here we try to open the updated database with its two new columns. If it fails, we can 
fall bacl< in the catch section and manually alter the existing database. 

Next, we refactor our saveTasl< function: 

saveTask: f unction(task, callback) { 

db.transaction(function(transaction) { 

// if the task id is not assigned, then insert 
if (! task. id) { 

transaction.executeSql( 

"INSERT INTO task(name, description, due, longitude, latitude) 

VALUES (?, ?, ?, ?, ?);", 

[task. name, task. description, 
task. due, parseFloat(localStorage[ "longitude" ] ) , parseFloat(localStorage[ "latitude" ] ) ] , 

function(tx) { 

transaction.executeSql( 

"SELECT MAX(rowid) AS id from task", 
[], 

function (tx, results) { 

task. id = results. rows.itetn(o) .id; 
if (callback) { 
callbackO; 
} // if 

} 

); 

} 

); 

} 

// otherwise, update 
else { 

transaction.executeSql( 




"UPDATE task " + 

"SET name = ?, description = ?, due = ?, completed = ?, 
longitude = ?, latitude = ? " + 

"WHERE rowid = ?;", 

[task. name, task. description, task. due, task. completed, 
parseFloat(localStorage[ "longitude" ] ) , par seFloat(localStorage[ "latitude" ] ) , task. id] , 

function (tx) { 
if (callback) { 
callbackO; 
} // if 

} 

); 

} // if..else 

}); 

} 

Our application is now totally location-aware; each task is bound to a location. In the 
next chapters, you will see how to combine this information with maps and process your 
location against other locations. 

Running Your Application Offline 

With all of the design work we've done, it wouid be hard for the average user to tell 
whether our application is native or web-based. However, there is still one big 
difference: cut off your Internet connection (or put your device in airpiane mode) and 
refresh your application, and you'll probably get a "page not found" error. What we need 
now is a way of running our application offline! 

Again, the new HTML5 standard will come to the rescue with its offline application 
cacfie. This new HTML5 feature will cache for us on the client side all the static 
resources: HTML, images, CSS, and JavaScript. The next time the user navigates to 
your application, the browser will use its cache instead of retrieving the files from the 
server, regardless of the connection status. 

The Offline Cache Manifest File 

How does it work? Offline caching relies on the cachie manifest file that is hosted on the 
web server. Iťs a simple text file document containing all the resources that have to be 
cached. The first important thing is the content type of this file. It has to be served with 
the MIME type text/cache-manifest. So, leťs see how we can configure Google App 
Engine (discussed in the previous chapter) to set the right MIME type for our cache file. 
Extra MIME types definition are specified in the web.xml file that you will find under your 
war/web-inf folder: 

<?xml version="l.O" encoding="utf-8"?> 

<web-app x[nlns= " http ://java. sun.com/xml/ns/javaee" version="2. 5"> 
[...] 

<mime-mapping> 

<extension>manifest</extension> 
<mime-type>text/cache-manifest</mime-type> 
</mime-mapping> 

</web-app> 
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By adding these parameters, Google App Engine will take care of setting the right 
content type for files with a manifest extension. Now that the server is configured, iťs 
time to create our cache manifest file. Create an empty text file called caclie. manifest 
that starts with this line: CACHE MANIFEST. We will pláce this file at the root of the web 
application (i.e., directly under the war folder). 

The next step is to list all the resources we want to cache— for us that will be the 
following: 

■ snippets/06/todolist.html 

■ snippets/06/css/proui.css 

■ snippets/Oótodolist.css 

■ js/jquery-1.4.2.min. js 

■ js/jquery.validate. js 

■ js/prowebapps . js 

■ snippets/06/iscroll. js 

■ snippets/06/todolist. js 

These are all the static resources we need to run the application; we just have to add 
them to the cache manifest file (all except the todolist.html file, which will be cached 
implicitly): 

CACHE MANIFEST 
css/proui.css 
snippets/06/todolist . css 
js/jquery-l.4.2.min. js 
js/ jquery . validate . j s 
js/prowebapps. js 
snippets/06/iscroll. js 
snippets/06/todolist . js 

The paths are relative to the location of the manifest file, but you couid also use the 
absolute paths. Now we finally have to declare the manifest file in our application, which 
we do by adding an attribute inside the HTML tag of the application page: 

<html [nanifest="cache.manifest"> 

Thaťs it! The application is ready to be cached the next time we will access it (online, of 
course). To check out that the files are correctly cached, we will use Chrome's web 
console: 

Creating Application Cache with manifest http://localhost:8080/cache. manifest 
Application Cache Checking event 
Application Cache Downloading event 

Application Cache Progress event (O of 7) http://localhost:8080/snippets/06/todolist.css 
Application Cache Progress event (l of 7) http://localhost:8080/js/jquery-l.4.2.min. js 
Application Cache Progress event (2 of 7) http://localhost:8080/js/prowebapps. js 
Application Cache Progress event (3 of 7) http://localhost:8080/snippets/05/todolist. js 
Application Cache Progress event (4 of 7) http://localhost:8080/js/jquery. validate. js 
Application Cache Progress event (5 of 7) http://localhost:8080/snippets/05/iscroll. js 
Application Cache Progress event (6 of 7) http://localhost:8080/css/proui.css 




Application Cache Progress event (7 of 7) 
Application Cache Cached event 

If you turn off your Internet connection now, the application will still work because the 
browser will retrieve the files from the local cache instead of the server. Going back to 
our scientist exannple from Chapter 5, the scientist will now be able to use his 
application everywhere he wants, even if he plans collecting data on the moon! 

But what happens if a resource file is modified? The offline cache mechanism uses a 
byte-to-byte comparison between the remote and cached manifest, so any change will 
be detected. 

Exploring Hidden Offline-Caching Features 

The offline-caching file also provides two other useful features: keywords NETWORK and 
FALLBACK. NETWORK can define resources that will aiways skip the cached resources and 
will aiways try to retrieve them from the server. FALLBACK comes in handy when you want 
to supply an alternativě cached resource to a resource that aiways has to be retrieved 
online when your connection is down. 

To illustrate this feature, leťs imagine that we want an icon showing whether we are 
online or offline, as in Figuře 6-5. 

Figuře 6-5. The "online" and "offline" icons 

We update our cache. manifest file as follows: 

CACHE MANIFEST 
css/proui.css 
snippets/06/todolist . css 
js/jquery-l.4.2.min. js 
js/jquery . validate. js 
js/prowebapps. js 
snippets/06/iscroll. js 
snippets/06/todolist . js 
FALLBACK: 

online. png offline. png 

Here we are saying that online. png shouid nevěr be cached; however, if we don't have 
a connection, we provide a fallback file, offline. png, defined by the FALLBACK keyword. 
(Note the trailing : for both keywords, which is required.) Leťs try it out and add this 
icon to our application. Regarding the cache manifest file, we just have to reference the 
Check icon in our page; showing the X icon will be handled by the caching mechanism. 

Add the icon to the rtiain view : 

<div id="main" class="view"> 
<hl>To Do List</hl> 

<img src="online.png" height="25" width="25"/> 
[...] 

</div> 
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Refresh your application and you shouid see something similar to Figuře 6-6. 
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Figuře 6-6. Application in online mode 

Turn off your internet connection and refresh your page, and you shouid see something 
lil<e Figuře 6-7. 



^IfflO 10:10am 




Task: Bring sample 3445 to HQ 



I Sample 3445 is stlll in sector 3A 
DUEIM: Odays 



START W0RKIN6 COHPLETE TASK 




Figuře 6-7. Application in offline mode 



Detecting Your Connection Status 



Beyond its caching capabilities, HTML5's offline-caching feature can provide some extra 
Utilities to deal witin offline mode. But tliese usually involve some more advanced use 
cases where offline caching will not be enougin. For instance, when you are offline, the 
synchronize function is quite useless, and it wouid be better if you couid hide the 
Synchronize button in this oase. 

Leťs see how we couId implement that. First, we must be able to detect whether we're 
online or not when we start the application. This may sound quite simple, but is actually 
more complicated than it seems. HTML5 has specified a feature that enables a web 
application to checkthe connection status: navigátor. online, which shouid return a 
Boolean value. Unfortunately, Chromé doesn't support this feature yet, and we have to 
use a workaround to simulate this behavior. 





NOTE: The HTML5 specification defines that the browser shouid be able to detect its connection 
status by using the JavaScript function navigátor . online. This function returns a Boolean 
value that can be used to used to change your application behavior for offline vs. online 
scenarios. 

Unfortunately, this feature is still not supported on the current Android browsers — but it will be in 
the next release. Even better, though, the browser that ships with Android 2.2 Froyo gives you 
more details about your connection type and speed. That gives you the option to adapt ] 
resources depending on your bandwidth. For more details, see 
http://davidbcalhoun.com/2010/using-navigator-connection-android. 

What we are going to do is make an HTTP request to a site, and, if we don't receive an 
answer after a configurable timeout, we can consider that we are offline. For some 
strange reasons, Ajax's jQuery function doesn't trigger a timeout event or an error event 
when you have no connection— for these reasons, we have to work around this by using 
jQuery's Timers plug-in; after tweaking it a bit, we shouid end up with something like 
this: 

$( '#synhcronize' ) .oneTime(3000, function(){ 
$( '#synhcronize' ) .css( "display ", "block"); 

}); 

$.ajax({ url: ' http: //query .yahooapis.com/vl/public/yql?"^- 
"q=select%20*%20from%20html%20where%20url%3D%22"+ 
encodeURIComponent(url)+ 
"%228if ormat=xml ' 8icallback=? ' j 
dataType: 'jsonp'j 
timeout: 3000j 
complete: function () { 

$( '#messages ' ) .stopTime(); 

} 

}); 



Competing with Native Apps 



We start by binding a timer to the Synchronize button. After three seconds, it will call the 
function defined iniine. This function masks the button after determining that there is no 
connection available. 

At the same time, we fire a simple YQL query (developer.yahoo.com/YOL) using an Ajax 
call, and, if the call is completed and successful, then we stop the timer and the button 
will stay visible. 

Summary 

You saw in this chapter that the look and feel of web-based applications can, in fact, 
compete with native applications. CSS3 and HTML5 are really beginning to break new 
ground in these areas. In this chapter, you learned how to enhance the user interface by 
adding animations and complex layouts, and you also learned how to deal with 
situations where no connection is available by implementing mechanisms that make 
web applications behave like native ones. 

In the next chapter, we'll focus on one of the features just introduced: working with 
location Information— commoniy called location-based services. 
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Exploring Interactivity 



In previous chapters, we explored building an Android web app similar to any desktop 
web app. Our experience of mobile development so far has been catering for a smaller 
display and tai^ing advantage of some of the HTML5 API features implemented in mobile 



In this chapter, we will take a slight break from building complete mobile web apps and 
explore interactivity through touch events and the HTML5 canvas. Throughout the 
chapter, we will look at: 

■ Touch events and where they are both similar to and different from 
mouše events for desktop browsers 

■ HTML5 canvas drawing and animation, including some simple best 
practices when working with canvas and animation 

■ Some more advanced animation techniques, such as how to produce 
more realistic animation through various techniques 

■ Some of the current things to watch out for when working with the 
canvas on Android, which also includes differences in the way the 
canvas behaves between different versions of the Android OS 



The HTML5 canvas is an extremely cool addition to the tools that you have at your 
disposal for building web applications in generál. The canvas element provides web 
developers a way to integrate a custom drawing area into their HTML layouts. This can 
be particularly useful and gives developers the ability to do more with their pages, 
whether that be adding some interactivity or displaying a graph. 

While not all browsers include support for the canvas tag, Androiďs WebKit browser 
does. This gives us the opportunity to explore using it in our applications, and possibly 
even writing simple games for Android purely using web technologies. While Flash 
(www.adobe.com/products/flashplayer) is normally the tool of choice for writing simple 
games for the Web, the HTML5 canvas and JavaScript do provide a compelling 



WebKit. 
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alternativě. And with cross-platform mobile support for Flash currently limited, this 
makes the canvas worth investigating. 

We will do that now by first having a look at some of the simple operations that can be 
completed using the canvas. 

In this first example, we will use the canvas to simply draw a line from the top-left corner 
of the display to the bottom right. First is the simplecanvas.litml file: 

<html> 
<head> 

<title>Simple Canvas Demo</title> 

<meta name="viewport" content="width=device-width; user-scalable=0; " /> 
<link rel="stylesheet" href=" . ./. ./css/proui.css" /> 

<script type="text/javascript" src=" . ./. ./js/jquery-l.4.2.[nin. js"></script> 
<script type="text/javascript" src=". ./. . /js/prowebapps. js"></script> 
<script type= "text/ javascr ipt " src= " simplecanvas . j s " ></script> 

</head> 

<body> 

<canvas id="simple"></canvas> 

</body> 
</html> 

Nothing much to taik about here, apart from the presence of the canvas tag, which by 
itself does absolutely nothing. Iťs time to look at the simplecanvas. js file that goes 
along with our HTML: 

(functionO { 

var canvas = null, 
context = null; 

function resetCanvasO { 

canvas = document.getElementById("simple"); 

// set the canvas height to the window height and width 
canvas. width = window. innerWidth; 
canvas. height = window. innerHeight; 

// get a reference to our drawlng context 
context = canvas. getContext("2d"); 

// now draw the line 
drawLineO; 
} // resetContext 

function drawLine() { 
context . beginPath ( ) ; 
context. moveTo(0, 0); 

context . lineTo(canvas .width^ canvas. height) ; 
context. stroke O; 
} // drawLine 

$(window).bind("resize", resetCanvas) .bind("reorient", resetCanvas); 

$(docutnent).ready(-Function() { 
window. scrollTo(0, i); 



resetCanvasO; 



Even here, there really isn't anything very complicated going on. Once you strip away 
the additional code to handle window resizing and so forth, the code does three things 
to draw the line: 

■ It gets a reference to the canvas and sizes the canvas to nnatch the 
window slze. This is done when we capture a window resize event or 
the device orientation changes (thanks to our previous work in Chapter 
1). 

■ It gets a reference to the 2d context of the canvas. To achieve this, we 
use the getContext method of a canvas object. 

■ It draws the line. This involves flagging to the canvas that we are going 
to draw a path with the beginPatli method. We then use the moveTo 
method to move to the top-left corner (moving draws nothing), and 
then follow that with the drawTo method to draw to the bottom-right 
corner. Finally, we tell the canvas to draw a line along the path we 
defined, using the stroke method. 

The result is displayed in Figuře 7-1 . 
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Figuře 7-1 . The canvas used to draw a diagonál line in the Android browser 



Drawing Interactively to the Canvas 

Now that we at least know how to create a simple canvas, leťs look at how we can do 
that interactively to create sonne unique mobile web apps. While jumping in and worl<;ing 
witin toucin events wouid be great, iťs wortin taking a little time to investigate Inow tinis is 
done using mouše events first— given that this is probably more familiar to us. 

Once we Inave the interactivity built using mouše events in a desktop browser, we will 
then explore how similar functionality wouId be implemented using touch events. By 
working with mouše events in the first instance and then moving to touch events, we will 
gain an understanding of some important differences between mobile interactivity and 
desktop interactivity. 

Interactivity: Tlie Way of tlie Mouse 

start by copying the previous simplecanvas.html file to a new HTML file called 
mousecanvas.html, and change the script tag to reference mousecanvas. js instead of 
simplecanvas. js. 

Next, leťs create our mousecanvas. js file. We'll start with the simplecanvas. js file as a 
base and make modifications so that we are drawing in response to the mouše events 
rather than once when the document loads. 

(functionO { 

var canvas = null, 
context = null, 
buttonDown = 0; 

function resetCanvasO { 

canvas = document. getElementById("simple"); 

// set the canvas height to the window height and width 
canvas. width = window. innerWidth; 
canvas. height = window. innerHeight; 

// get a reference to our drawing context 
context = canvas. getContext("2d"); 
} // resetContext 

$(window) .bind("resize" j resetCanvas) .bind("reorient" , resetCanvas); 

$(document) .ready(function() { 
window. scrollTo(0, l); 
resetCanvasO; 

document. body. addEventListener("mousedown"j f unction(evt) { 
if (buttonDown === O) { 

context . moveTo(evt . pageX, evt . pageY) ; 

} // if 



++buttonDown; 

}, falše); 



document.body.addEventListener("mousemove"j f unction(evt) { 
if (buttonDown > O) { 

context . lineTo(evt . pageX, evt . pageY) ; 
context . stroke O ; 

} // if 
}, falše); 

document.body.addEventListener("mouseup", f unction(evt) { 

--buttonDown; 
}, falše); 



}); 
})(); 

To test this code, run it using an HTML5-compatible desktop browser. As mentioned in 
previous chapters, Chromé is a good choice, as it is based on WebKit and has some 
excellent tools support. Figuře 7-2 shows a sample drawing after mouše interaction. 



NOTE: You may be wondering why we are running code in a desktop browser when this is a 
book on mobile development. WeII, in the preceding example, we are working with mouše 
events, so a desktop browser is required. Additionally, as you begin to work more with mobile 
web app development, you will find desktop browsers are an important part of your development 
process. There is little or no development tools support on mobile browsers at this stage, so iťs 
important not to forget your desktop-based WebKit browser as an important part of your 
development tool set. 
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Figuře 7-2. í/smg moí/se ei/enřs and the HTML5 canvas allows tragic artists to express themselves. 

While the preceding code works weil enough in a browser, it does absolutely nothing 
useful on an Android device— uniess of course you consider being able to scroll tlie title 
bar that we Inid bacl<; into view useful. 

Interactivity: The Way of Touch 



in transitioning to using toucin events, leťs first take a look at the event-naming 
conventions, as displayed in Table 7-1 . 

Table 7-1. How Touch Events Relate to Respective Mouse Events 



Interaction Style 


Start Event 


"Continue" Event 


End Event 


Mouse 


mousedown 


mouseover 


mouseup 


Touch 


touchdown 


touchmove 


touchup 



The naming of these functions gives us a clue to the differences between working with 
touch and mouše events. Both mouše and touch events have "down" and "up" events 
to signify that interaction has started and ended, respectively. 

The primary difference, however, is between the mouseover and touchmove events. A 
touch event has no concept of hovering, and thus we have no touchover event, so it is 
replaced with the touchmove event, signifying that a touch event has started and the 
touch points are changing. This is an important point to note, as familiar web concepts 
such as "hover states" have no effect on mobile devices, so iťs important to consider 
alternativě mechanisms to provide feedback to your app users. 

We will now create our touchcanvas.html and touchcanvas. js files. As per the mouše 
canvas example, the HTML file is very simple, so just make a copy of the previous 
mousecanvas.html file and tweak the references. 

Our touchcanvas. js file is more or less a replacement of the mouše event handlers with 
the relevant touch event handlers: 

(functionO { 

var canvas = null, 
context = null; 

function resetCanvasO { 

canvas = document.getElementById("simple"); 

// set the canvas height to the window height and width 
canvas. width = window. innerWidth; 
canvas. height = window. innerHeight; 

// get a reference to our drawing context 
context = canvas. getContext("2d"); 
} // resetContext 

$(window) .bind("resize", resetCanvas) .bind("reorient", resetCanvas); 

$(docutnent) .ready(function() { 
window. scrollTo(0, l); 
resetCanvasO; 

document.body.addEventListener("touchstart"j f unction(evt) { 
context . beginPath ( ) ; 

context. moveTo(evt.touches[o] .pageX, evt.touches[o] .pageY); 

evt . preventDef ault () ; 

}, falše); 

document.body.addEventListener("touchmove"j f unction(evt) { 
context. lineTo(evt. touches[o] .pageX, evt.touches[o] .pageY); 

context. stroke(); 
}, falše); 

document.body.addEventListener("touchend", function(evt) { 
}, falše); 
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With the preceding code implemented, you shouid be able to draw using touch on your 
Android device and simulate touch events in tine emulátor. Figuře 7-3 shows an 
example. 



Figuře 7-3. More advanced drawings are possible given the intuitive nature of the touch interface. 

The primary differences between this code and the mousecanvas. js file are: 

■ With mouše events, mouše button information is included to signify 
whether the left, right, or other button was pressed. When it comes to 
touch events, we have no concept of varying buttons, and as such 
there is no need to monitor button states. Given this situation, the 
touchstart handler has no code to do this, and the touchend event 
handler does nothing and couid quite simply be removed. 

■ References to evt . pageX and evt . pageY are replaced with references 
to the touches array of the event object. In our example, we reference 
evt.touches[o] .pageX and evt.touches[o] .pageY to get the screen 
coordinates of the first touch. 

■ The touchstart handler makes a call to the preventDef ault method of 
the event object to telí the browser not to take any further action with 
this event. Without this call, the browser will initiate scrolling on the 
window; this is not desirable behavior, as it wouid interfere with our 
attempts to draw in the canvas area. 

With the touch canvas example complete, you shouid now have a basic understanding 
of how to use both the HTML5 canvas and touch interactivity to create some simple 
Interactive mobile web apps. Time now to take this further. 




r 



NOTE: In the last few chapters, we have been exploring components of the emerging HTIVIL5 
spec. As such, it might be natural to expect that touch is part of that specification; however, it 
isn't. 

A separate W3C working group has been set up for standardizing touch interaction, so over time 
we wouid expect the way we implement touch interfaces to change slightly as the different 
organizations working with touch interfaces come to agree on a standard implementation. 

If you are interested, the URL for the working group is 
www.w3.org/2010/07/touchinterface-charter.html. 



Implementing Canvas Animation 

This next section is focused on exploring animation using the HTML5 canvas and how 
simply that can be implemented. We will have a look at a couple of different examples of 
animation using the canvas, using a mix of animation using both simple drawings and 
images. In each of these examples, simple touch events will be used to drive the 
samples. 

In addition to the animations, we will also explore the impact that device DPI (or dots- 
per-inch) has on working with images in the canvas. This is probably one of the more 
frustrating parts of using HTML5 on Android, as its effects differ between different 
versions of the operating systém; however, we will look into some strategies for working 
around the problém. 



Creating an Animation Loop 

If youVe worked with JavaScript in the past, you will be familiar with both the 
setTimeout and setinterval functions. These functions allow a block of JavaScript to 
execute aftern milliseconds or every n milliseconds, respectively. In the case of 
animation, we want a recurring event, so we will be using the setinterval method. 

Again, for this example, we oniy need the barest of HTML files, so create a new HTML 
file called drops.html and a corresponding JavaScript file (you know the drill). We will 
work through a few animation examples in this chapter, and each example will be 
structured in a similar manner to the example that follows. Our first animation example 
implements a simple animation loop that simulates raindrops in the browser. 

Here is the initial code for drops, js: 

(functionO { 

var canvas = null, 
context = null, 
drops = []; 



function resetCanvasO { 
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} // resetContext 
function animateO { 
} // animate 

$(window) .bind("resize"j resetCanvas) .bind("reorient", resetCanvas); 

$(document) .ready(function() { 
window.scrollTo(0, l); 
resetCanvasO; 

document.body.addEventListener("touchstart", function(evt) { 
// add the new drop 
drops. push({ 
size: 2, 

maxSize: 20 + (Math.randomO * 50), 
x: evt.touches[o] .pageX, 
y: evt.touches[o] .pageY 

}); 

// prevent screen scrolling 
evt . preventDef ault ( ) ; 
}, falše); 

setlnterval(animate, 40); 



The code is structured in a similar fashion to previous examples, with the resetCanvas 
function used to handle both initialization and resizing the canvas appropriately. 

We have implemented the touclistart handler to add new "drops" to our drops array, 
defining an initial size and a randomly generated maximum size, and capturing the x and 
y coordinates of the touch position. 

We then have the animation loop, which is implemented in the animate function and 
created by using the setinterval call. We have defined a delay of 40 milliseconds, 
which equates to approximately 25 frames of animation per second. 



Drawing a Frame of Animation 

Before we have a look at the actual animate function implementation, first we will have a 
look at the things that we shouid do in a single pass of drawing our animation. To try to 
explain this clearly, we have brol<;en the process down into six simple steps: 

1. Save the canvas context. Saving the canvas context saves Information about the 
current canvas statě, which can be restored later. This is particularly important 
when you are writing code that you want to integrate with other canvas-drawing 
code. Without saving and restoring canvas statě, it wouid be quite possible to 
effect the other draw code that is making similar changes. 



L 



2. Clear the background. The first step in drawing an animation frame usually 
involves clearing tlie bacl<ground from wliat lias been drawn In the previous 
frame. As you become more comfortable with drawing to the canvas, however, 
you may want to limit doing this to squeeze more performance out of your 
animations. For what we are doing here, though, clearing the background is Ideál. 

3. Adjust canvas parameters. Before drawing to the canvas, you may want to change 
parameters such as stroke or flll style, and also colors. 

4. Draw the animation frame. Draw the animation frame using the various canvas 
methods provided. We'll look at an example shortly that touches on a few 
elements of this, but, for further Information, the Mozilla Developer Center Canvas 
Tutoriál is an excellent resource 

(https : //developer. mozilla.org/en/Canvas_tutorial). 

5. Perform animation loop logic. It is likely that, to effect any kind of animation, you 
will need to update variable values, perform calculatlons, and so on. Generally, 
within the animation loop Is an effective pláce to perform this kind of logic. 

6. Restore the canvas statě. Once the animation loop has been completed, restore 
the canvas statě to prevent modiflcations that have been made to the canvas 
within the loop (such as changes to flll or stroke style) being used In other parts of 
the application. 

NOTE: While some wouid suggest that saving and restoring the canvas statě Is optlonal 
depending on your implementatlon, our advice wouId be to Implement the logic at least in the 
first Instance, as It is the best chance you have of making your code reusable within another 
application. If for some reason (such as performance optlmization) It becomes necessary to 
remove the state-saving and restoring steps, then do so with care. 



A Working Example 

With an understanding of the steps that are required In a single pass of the animate 
functlon, leťs now have a look at the code: 

function animateO { 
context.saveO; 

try { 

// clear the drawing surface 

context.clearRect(0, O, canvas. width, canvas. height); 

// set a stroke style 

context.strokeStyle = "rgba(68, 221, 255, 0.5)"; 
context.lineWidth = 4; 

// iterate through the drops and draw them to the canvas 
var ii = 0; 



while (ii < drops. length) { 
// draw the drop 
context . beginPath ( ) ; 

context.arc(drops[ii] .X, drops[ii].y, drops[ii] .size, O, 2 * Math.PI, 

falše); 

context . stroke O ; 

// increase the size of the drop 
drops[ii] .size += 2; 

// if the drop has exceeded its max size, then remove it 
if (drops[ii] .size > drops[ii] .maxSize) { 
drops. splice(ii, l); 

} 

// otherwise, on to the next drop 
else { 

ii++; 
} // if..else 
} // while 

} 

finally { 

context . restore( ) j 
} // try.. finally 
} // animate 

The code in the animate function creates an animation that will produce a result similar 
to that shown in Figuře 7-4. 
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Figuře 7-4. /l snapshot of the animation created by our drops.js tile 



Looi^ing at the preceding code, we can see that all of the items that were outlined 
previously have been covered: 



■ The context. save method is called to save the canvas statě as per 
step 1 . We then open a try . .finally block to implement steps 2 
through 5. 

■ The first call in the inner block is then calling the context. clearRect 
method to clear the canvas background. This covers step 2 in our 
process, but, as mentioned earlier, in some cases you may want to 
rennove this to optimize performance. 

■ We then move to step 3, which is adjusting the canvas parameter for 
drawing the display. In our sample, we are adjusting the strol<eStyle 
and lineWidth parameters of the canvas context. Additionally, note 
our use of the CSS3 rgba function to specify the strokeStyle (see 
WWW.W3 .org/TR/css3-color/#rgba-color for more info on the rgba 
function). The rgba function allows us to provide the red, green, blue, 
and finally alpha values for the color of the stroke (or fill). This provides 
US with the ability to create semitransparent lineš and fill, which can 
provide some visually appealing effects. 

■ Then step 4— we draw. In the case of our example, steps 4 and 5 are 
very much intermingled, which is probably something that will occur in 
many implementations. Our draw code here is simply drawing circles 
for each of the drops on the display, but you will probably notice that a 
simple circle function is nowhere in sight. Instead, we use paths. At 
first glance, this is a little disconcerting — but don't worry, you will get 
used to using paths, and we cover this in a little more detail soon. 

■ Step 5 then follows; as mentioned, this is mixed fairiy tightly with step 
4, as we are both drawing and updating multiple drops when we are 
drawing a single frame of animation. In our code, the slze of the drop 
is increased, and, if it reaches a certain slze, then it is removed from 
the drops that we will draw. 

■ Finally, we break out of the try block in the try. .finally loop and 
execute the finally section. The finally section aiways executes, 
and in this case it restores the canvas statě as per step 6. 

A Quick Overview of Canvas Paths 

You will notice as you work with the canvas that it is a fairiy low-level API. Different 
people have different opinions on this, and, while the HTML5 standard is far from locked 
down, it is likely that it will remain this way. 

One example of the low-level nature of the canvas involves the extensive use of paths 
rather than higher-level abstractions (such as circles, ellipses, etc). As shown in the 
previous code sample, drawing a circle involved the following code: 

context . beginPath ( ) ; 

context. arc(drops[ii] .Xj drops[ii].y, drops[ii] .size. O, 2 * Math.PI, falše); 
context. strokeO; 
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This is a good example of how paths are used: 

1. We tell the canvas context that we are starting to work with a path by calling the 
beginPath method. 

2. We then perform the relevant path-drawing operations to create the shape(s) we 
require. In the preceding example, we use the are method to draw a circle, but we 
couid also use the lineTo or rect methods to draw lineš and rectangles also. 

3. Once all the path-drawing operations have been completed, either the stroke or 
f ill methods of the canvas context are called to draw or fill the specified path. 

While it takés a bit of getting used to, having access to low-level path operations allows 
for very flexible implementations in your code. It isn't for everyone, though, and 
JavaScript libraries such as fabric. js (see http://github.com/kangax/fabric.js) can 
definitely simplify the process of working with the canvas if you are interested. 

NOTE: As previously mentioned, this chapter is meant to serve as an introduction to what can be' 
achieved using the HTML5 canvas, and we suspect that you couId write an entire book on the 
topič. As such, it takés significantly more than a small section of the book to explain path 
operations in any depth. For further information and a solid tutoriál on the topič, we wouid once 
again recommend the Mozilla resources on the topič: 

^https: //developer. mozilla.org/en/Canvas_tutorial/Drawing_shapes. 

Now armed with a basic understanding of an animation loop and how you can use the 
HTML5 canvas and touch to create simple Interactive web apps, we'll have a look at 
some more complicated examples. 




Drawing Images: Accounting for Device DPI 

Over the next few examples, our goal will be to show a car animating across the screen. 
At the same time, we will be exploring the impact of device DPI on various versions of 
the Android OS, and some strategies that can be used to deal with this. 

To get started, once again create an HTML file to contain the application, but with a 
minor difference this time: 

<html> 
<head> 

<title>Simple Car Animation</title> 

<meta name="viewport" content="target-densitydpi=device-dpij width=device-width; 
user-scalable=0; " /> 

<link rel="stylesheet" href=" . ./. ./css/proui.css" /> 

<script type="text/javascript" src=" . ./. ./js/jquery-l.4.2.min. js"></script> 
<script type="text/javascript" src=". ./. ./js/prowebapps. js"></script> 
<script type="text/javascript" src="car. js"></script> 

</head> 

<body> 

<canvas id="main"></canvas> 



</body> 
</html> 



In Chapter 2, we looked at the various values that can be specified in the viewport meta 
tag. Here is an example where setting the target-densitydpi actually nnakes a 
difference to what is displayed in the browser. Figuře 7-5 illustrates the difference 
between specifying and not specifying the target-densitydpi setting when using a high 
DPI device. 
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Figuře 7-5. The difference between including and not including tfie target-densitydpi (on tfie left, there is no 
setting; on the right, itis included) 



Since a target-densitydpi setting has not been included in the viewport meta tag, the 
emulátor has automatically scaled up the image. This isn't really what is desired, as this 
can make the car start to look a little pixelated. 

Once the device is instructed to use the device-dpi, it no longer scales, and the quality 
of the image is improved. There is still more work to do regarding device pixel ratios in 
our JavaScript, but thaťs a start. 

Speaking of JavaScript, here is our car. js file: 

(functionO { 

var canvas = null, 
context = null, 
car = null, 
carX = O, 
endPos = null; 

function resetCanvasO { 




} // resetContext 

function animateO { 
context.save(); 
try { 

if (endPos && car && car.complete) { 
// clear the drawing surface 

context.clearRect(Oj O, canvas.widthj canvas.height); 
// draw the car 

context.drawImage(car; carX - car.width, endPos.y - car.height); 

// draw an indicator to highlight the difference between the car and 
context . beginPath ( ) ; 

context.arc(carX, endPos.y, 5, O, Math.PI * 2, falše); 
context. fill(); 

// increment the car x 
carX += 3; 

// if the car x is greater than the end pos, then rertiove it 
if (carX > endPos.x) { 

endPos = null; 
} // if 
} // if 

} 

finally { 

context. restore()j 
} // try.. finally 
} // animate 

$(window) .bind("resize", resetCanvas) .bind("reorient" , resetCanvas); 

$(document) .ready(function() { 
window.scrollTo(0, l); 
resetCanvasO; 

document.body.addEventListener("touchstart", function(evt) { 
endPos = { 

x: evt.touches[o] .pageX, 
y: evt.touches[o] .pageY 

}; 

carX = 0; 

// prevent screen scrolling 
evt . preventDef ault ( ) ; 
}, falše); 

// load our car image 
car = new Image(); 
car.src = "car.png"; 

setlnterval(animate, 40); 



In the first version of this file, we included a marker to help us understand the impact of 
device DPI when rendering images. To gain an understanding of how this works, run an 
emulátor using an Android OS 2.1 AVD image with a high-resolution screen DPI skin 
(something like WVGA800 — see Chapter 1 for details on how to do this). This will allow 
US to compare positioning in an emulátor running in medium DPI vs. high DPI mode. 



NOTE: You may be wondering why a specific version of the Android emulátor is required to 
demonstrate the difference between a standard resolution and a high-resolution display. This 
due to some differences in behavior between different versions of the Android OS, and it is 
explained in more detail soon. 



Figures 7-6 and 7-7 illustrate the difference between the two device pixel ratios and the 
impact on drawing images. 
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Figuře 7-6. /l device pixel ratio of 1 means that both aur marker and image are drawn at the position of the 
touch. 
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Figuře 7-7. /l rfewce p/xe/ rař/o oř 1.5 shows that images require adjustment. Guidelines have been added. 

Not surprisingly, the position at which the screen was touched and the end position of 
the car differ by a factor of 1 .5, while the marker is drawn right where iťs meant to be. 
For this reason, when we are drawing images to the canvas, we will need to apply some 
scaling to ensure that those images appear in the correct location. 

The following code demonstrates the adjustments required to display the image in the 
correct location: 

// draw the car 
context.drawImage(car, 

(carX / window.devicePixelRatio) - car.widthj 

(endPos.y / window.devicePixelRatio) - car.height); 

// draw an indicator to highlight the difference between the car and 
context . beginPath ( ) ; 

context.arc(carXj endPos.y, 5, 0, Math.PI * 2, false)j 
context. fill(); 

With this code modification made, the car image is drawn in the correct location and 
appears at a position in line with the marker. 



NOTE: For the moment, if you are targeting 2.1 as an application platform we would recommend 
that you look at including appropriate windowDevicePixel ratio tweaks (plus some browser 
detection code). If you feel comfortable targeting 2.2 and above oniy, then you are able to let the 
Android browser deal with things rather than have to account for this behavior yourself. 

Addltionally, If you are worklng on an Android 2.2 development platform, then adjust the sample 
code in this chapter, removing any instance that we divide by the 
window. devicePixelRatio. 



A Tale of Three Androids 

One of the primary criticisms of Android to date has been around the fragmentation of 
the OS versions that are "in the wild." This a problém primarily because different 
versions of the OS may do something different from another version— yielding 
unexpected results. While this can be frustrating to work with as a developer, it is worth 
persevering, as you are ultimately writing code that will work (with minor nnodification) on 
any mobile device with a WebKit browser. 

We find ourselves in that situation when we compare the techniques required to position 
images in high DPI devices for versions of Android up to and including 2.1 with those 
required for versions 2.2 and beyond. Figuře 7-8 illustrates the difference in image 
positioning when compensating for devicePixelRatio the same way across three 
different versions of the Android OS. In each of the images, the touch start position was 
the center of the screen, but you can see the resulting image position in 2.2 no longer 
requires the compensation applied for previous versions. 
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Figuře 7-8. Android 1.6, 2. 1, and 2.2 (shown from left to ríght) compensate for device DPI differently. 



In reality, Android OS version 2.2 (code-named Froyo) implements the functionality 
correctly. This is great, as having to compensate for devicePixelRatio in JavaScript 
once an appropriate viewport meta tag is supplied definitely feels like double handling. 

With the need to support more versions of Android than just 2.2, though, we need to 
implement a method of detection that will provide Information on how the current device 
is rendering images to the canvas. This information can then be used to determine 
whether we need to apply adjustments in the code. 



NOTE: Ideally, we would have loved to Include the code to demonstrate effective detection in this 
chapter. Unfortunately, however, neither simple browser detection 
(www. quirl<smode.org/js/detect. html) nor feature detection 
(https://developer.mozilla.org/en/Browser_Feature_Detection) techniques are 
effective at determining whether our offsets shouid be applled. We have started a GitHub forl< of 
the excellent Modernizr project (www.modernizr.com) to lool<at providing suitable detection for 
this situation. So, If you are lool<ing to worl< with the HTML5 canvas on Android, we would 
recommend checking out the followlng repository: mhhh^^HHHBHHBM^H 
http://github.com/sidelab/Modernizr. 



Once suitable detection has been Implemented, details on how to implement the technique wlll 
be described on the project wiki: http : //github . com/sidelab/Modernizr/wiki. 



Advanced Animation Techniques 



Our previous animation examples Inave been a good introduction to implementing 
simple animation witin tine HTIVÍL5 canvas, but tine animations obviously weren't smooth. 
In this section, we will investigate tecinniques tínat will help to make the animation 
smoother and more believable. 

Creating Realistic Movement in Animations 

In both of the previous examples, we implemented very primitive techniques for 
animating our display. For instance, the car animation loop simply incremented the x 
position of the car by 3 pixels each time the function was called. Did anyone think that 
looked believable? No, we didn't think so. Leťs fix that first of all. 

To do this, we will use easing to smooth the start or end of the animation (or both). For 
instance, applying some appropriate easing to our animation wouid make the car appear 
to accelerate up to speed or brake to a stop. 

As this isn't a book specifically focused on animation, we won't go into depth on what is 
involved in creating an easing effect nor attempt to write code from the ground up. 
Rather, we will use some of Robert Penner's existing easing equations (see 
www.robertpenner.com/easing) to create a more realistic effect of motion for our car. 
These equations were first written for Flash, but have a look in the source of many of the 
JavaScript libraries that implement easing animation and you will find a reference to 
Roberťs excellent work. 

Iťs likely we will make use of these easing equations again, so leťs add them to our 
prowebapps. js file: 

PROWEBAPPS = (functionO { 

var module = { 

Easing: (function() { 
var subModule = { 

Linear: function(t, b, c, d) { 
return c*t/d + b; 

}, 

Sine: { 

In: function(t, b, d) { 

return -c * Math.cos(t/d * (Math.PI/2)) + c + b; 

}, 

Out: function(tj b, c, d) { 

return c * Math.sin(t/d * (Math.PI/2)) + b; 

}, 

InOut: function(t, b, d) { 

return -c/2 * (Math.cos(Math.PI*t/d) - l) + b; 



} 

} 

}; 

return subModule; 
})(), 

}; 



return module; 

})(); 

In the preceding code, we added two of the many easing functions available in Penner's 
work. Each of these easing functions tai<es four parameters: 

■ t: Tlie elapsed time for the animation 

■ b: The beginning value, or the value we are easing from 

■ c: The change value, or the difference between the end value and the 
start 

■ d: The duration of the animation 

So, by way of example, the following wouid telí us what the value shouid be if we were 
easing from O to 500, 600 mllliseconds in, for a 2-second animation: 

newValue = PROWEBAPPS. Easing. Linear(600, O, 500, 2000); 

And if we were easing from 11 00 to 1 700 at the same point in time: 

newValue = PROWEBAPPS. Easing. Linear(600, 1100, 600, 2000); 

If that doesn't mal<e complete sense yet, don't worry— it will by the time we have a few 
examples down. Leťs integrate the easing code into our car animation sample. We 
wouId suggest creating a separate JavaScript file so that you can do a side-by-side 
comparison. 

Here's the sample code for car-easing. js: 

(function() { 

var ANIMATION_0URATION = 1000; 

var canvas = null, 
context = null, 
car = null, 
endPos = null, 
animationStart = 0; 

function resetCanvasO { 

} // resetContext 

function animateO { 
context. save(); 



try { 

if (endPos && car && car.complete) { 
// determine the elapsed time 

var elapsedTime = new Date().getTime() - animationStart, 
carX = PROWEBAPPS.Easing.Linear( 
elapsedTime, 
O, 

endPos.x, 

ANIMATION_DURATION) - car.width; 

// clear the drawing surface 

context.clearRect(0, O, canvas.width, canvas.height); 
// draw the car 

context.drawItnage(car, carX, endPos.y - car.height); 

// if the car x is greater than the end pos, then remove 
if (elapsedTime > ANIMATI0N_DURATI0I\1) { 

endPos = nullj 
} // if 

} // if 

} 

finally { 

context.restoreO j 
} // try.. finally 
} // animate 

$(window) .bind("resize"j resetCanvas) .bind("reorient", resetCanvas); 

$(document) .ready(function() { 
window.scrollTo(0, l); 
resetCanvasO; 

document.body.addEventListener("touchstart", function(evt) { 
endPos = { 

x: evt.touches[o] .pageX / window.devicePixelRatio, 
y: evt.touchesfo] .pageY / window.devicePixelRatio 

}; 

// capture the animation start tick count 
animationStart = new Date() .getTime(); 

// prevent screen scrolling 
evt . preventDef ault ( ) ; 
}, falše); 

// load our car image 
car = new Image(); 
car.src = "car.png"; 

setlnterval(animatej 40)j 



We'll quickly go through the notable sections of this code: 




■ The "constant" ANIMATION_DURATION is used to set the time that the 
animation will run for. 

■ Each time the animate function is called, and when the animation is 
first triggered (in the touclistart event handler), we use a call to new 
Date() .getTime() to determine the current time in milliseconds. In the 
context of the animate function, we use that figuře to determine how 
much time has elapsed since the animation started. 

■ The calculation of the carX variable has changed to use the 
PROWEBAPPS.Easing.Linear function. This variable can now be 
declared locally in that function. The Linear easing function doesn't 
actually perform any easing. Once we have validated our 
modifications, we will drop in the Sine easing functions to replace the 
Linear easing. 

■ Determining that the animation has reached its finál value is now done 
based on a comparison between elapsedTime and the animation 
duration. This is done as some easing functions return higher values 
than the destination on the way to the end value (sounds confusing, 
but you'll see). 

Running this sample shouid display the car animating, but still show an animation that 
doesn't look any smoother— the car still stops very abruptly. Leťs fix that now. Replace 
the reference to PROWEBAPPS.Easing.Linear with PROWEBAPPS. Easing. Sine. Out, and you 
shouid see the car image slow down as it approaches the x coordinate of your touch 
start point. 

NOTE: The majority of Penner's easing equations come in three variants: In, Out, and InOut. The 
In variant will apply the easing at the beginning of the animation, and, in the case of our car, this 
means it will start slow and then speed up. Easing out means that values will have easing IM 
applied as the animation approaches its finál value, which is exactly what we want with our 
car — for it to slow to a stop. An InOut easing function applies easing at both the start and end of 
the animation. We'd recommend playing around with the different variants to get a feel for how , 
[ they work. 



ADDING AN ADDITIONAL EASING FUNCTION TO PROWEBAPPS 



As mentioned previously, we really oniy implemented one of Penner's easing functions for our animation, 
and there are many more useful easing functions in his library. It is a reasonably simple exercise to tal<e 
anotlier of his existing samples from ActionScript and port it to JavaScript and intothe prowebapps. js 
file. One that wouid lool< good with the car animation (and a personál favorite of mine) wouid be the "Bacl< 
Out" easing function. 

The Bacl< Out easing function is a good picl< for this particular situation as the effect is to slightly overshoot 
the actual animation end point, and then slowly reverse bacl< to the target point. In the case of a car, this 
looks quite believable. We don't think you'll be disappointed with whichever additional easing function(s) 
you may choose. Trust us, iťs hard to stop applying easing to your animations once you start. 



Canvas Transformations and Animation 

It is impressive how powerful tlie HTML5 canvas is, and what can be achieved with it 
using minimal code can definitely give you a buzz. In this next section, we will introduce 
sonne transfornnation operations that we can use to provide additional animation to our 
car. 

Before we get into that, though, we'll have a look at a simple example to get an overview 
of how transformations operáte. There are a number of different transformation 
operations that are available to you when using the canvas; however, since this isn't a 
book on the HTML5 canvas specifically, we will onIy touch on two operations that we 
require to expand on our sample: 

ki translate: The translate method shifts the origin of the canvas to the 
specified position. By default, the origin (0,0) of the canvas refers to 
the top-left corner, but that can be changed using the translate 
method. 

■ rotate: The rotate method rotates the canvas around the origin. Used 
in combination with the translate method, it can do some very cool 
things. 

^ NOTE: Once you start using transformation operations, you won't want to have to reverse 
changes to the context statě all the time. This is why we recommended getting into the hábit of 

j using the save and restore methods of the canvas, as they will prevent you from having to 
keep track of the various transformations and statě changes you make. 

j For more Information on canvas transformations and the importance of the save and restore 
methods, we highiy recommend the Mozilla Developer Center's information on the topič, at 
https://developer.mozilla.org/en/Canvas_tutorial/Transformations. 
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ixploring Interacti 



Leťs take a look at what we can do with translate and rotate methods in a simple 
exannple. Create another HTML file for this example, rotation . html, and base it on one 
of our earlier examples. Then create a rotation. js file and include that in the HTIVIL: 

(functionO { 

var canvas = null, 
context = null, 
angle = 0; 

function resetCanvasO { 

} // resetContext 

function animateO { 
context. save(); 
try { 

// clear the drawing surface 

context. clearRect(Oj O, canvas. width, canvas. height); 

// set the origin of the context to the center of the canvas 
context. translate(canvas.width * 0.5, canvas. height * 0.5); 

// rotate the canvas around the origin (canvas center) 
context . rotate(angle) ; 

// draw a rectangle at the specified position 
context. fillStyle = "#FFOOOO"; 
context. fillRect(-30, -30, 60, 60); 

// increment the angle 
angle += 0.05 * Math.PI; 

} 

finally { 

context. restoreO; 
} // try.. finally 
} // animate 

$(window) .bind("resize" j resetCanvas) .bind("reorient" , resetCanvas); 

$(document) .ready(function() { 
window.scrollTo(0, l); 
resetCanvasO; 

setlnterval(animate, 40); 



While transformations can sound difficult, the preceding is very simple code and sinouid 
produce a result similar tínat displayed in Figuře 7-9. 
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Figuře 7-9. /l rotating animation can be created simply by using varíous canvas transformation operations. 

Just quickly, we will walk through the code from this implementation of the animate 
function: 

1. The translate method is called shortly after the canvas is cleared, and we set the 
origin of the canvas to the center of the canvas. 

2. The rotate method is then called, passing in the angle of rotation (in radians) that 
shouid be applied. 

3. Next, a canvas f illStyle is specified, and the f illRect method is called to draw 
a solid-red square at the center of the canvas. 

4. The value of the angle variable is then incremented for the next time the square is 
drawn. 

When working with transformations on the canvas, it is important to remember a few 
things: 

■ The translate method shifts the origin ofthe canvas, which means 
that both of your subsequent transformation operations and any draw 
operations are now made relative to the point you translated to. 

■ Calling context.saveO prior to performing the translation, and then 
using context.restoreO after, will help to make using transformations 
manageable. AIthough not aiways appropriate, having the origin shift 
back to a constant point after transformation operations will make your 
draw code easier to manage and keep track of. 
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Transformations and Our Car Animation 

Getting back to our car animation, we're sure you can thinl<; of a way that we might be 
able to use rotation to mal<e our animation more believable again. TInaťs rigint, leťs 
mai^e those wheels turn. Obviously, we will require a separate wlieel image to be able to 
apply tine rotation to it, and not the rest of the car. Lucl<;ily, we have one. 

Create a new HTIVIL file for this demo, called wheelie.html, and a corresponding 
wheelie. js file for the code: 

(functionO { 

var ANIMATIONDURATION = 3000; 

var canvas = null, 
context = null, 
car = null, 
wheel = null, 
endPos = null, 
endAngle = O, 
wheelOffset = O, 
animationStart = 0; 

function resetCanvasO { 

} // resetContext 

function drawWheel(x, y, rotation) { 
if (wheel && wheel. complete) { 
context. save(); 
try { 

// translate and rotate around the wheel center 
context. translate(x, y); 
context. rotate(rotation); 

// draw the wheel image (taking into account the wheel image size) 
context. draMlmage(wheel, -wheelOffset, -wheelOffset); 

} 

finally { 

context. restoreO; 
} // try.. finally 

} // if 
} // drawWheel 

function animateO { 
context. save(); 
try { 

if (endPos && car && car. complete) { 
// determine the elapsed time 

var elapsedTime = new Date() .getTime() - animationStart, 
carX = PROWEBAPPS.Easing.Back.Out( 
elapsedTime, 
O, 

endPos. x, 

ANIMATION_DURATION) - car.width, 
wheelAngle = PROUEBAPPS.Easing.Back.Out( 



elapsedTime, 
O, 

endAngle, 

ANIMATION_DURATION); 

// clear the drawing surface 

context.clearRect(0, O, canvas.width, canvas.height); 
// draw the car 

context.drawImage(car, carX, endPos.y - car.height); 

// draw the wheels at the appropriate position 
draMUheel(carX + 17, endPos.y - 10, wheelAngle); 
draMUheel(carX + 99, endPos.y - 10, wheelAngle); 

// if the car x is greater than the end pos, then remove 
if (elapsedTime > ANIMATION_DURATION) { 

endPos = null; 
} // if 
} // if 

} 

finally { 

context.restoreO; 
} // try.. finally 
} // animate 

function startCar(destX, destY) { 
endPos = { 
x: destX, 
y: destY 

}; 

// calculate the end angle based on the end x position 
endAngle = (endPos. x / window.innerlAlidth) * 8 * Math.PI; 

// capture the animation start tick count 
animationStart = new Date() .getTime() j 
} // startCar 

$(window) .bind("resize" j resetCanvas) .bind("reorient", resetCanvas); 

$(document) .ready(f unctionO { 
window.scrollTo(0, l); 
resetCanvasO; 

document.body.addEventListener("touchstart", function(evt) { 
startCar( 

evt.touches[o] .pageX / window.devicePixelRatiOj 
evt.touches[o] .pageY / window.devicePixelRatio); 

// prevent screen scrolling 
evt . preventDef ault ( ) ; 
}, falše); 

// load our car image 
car = new Image(); 
car.src = "car.png"; 




wheel = new Image(); 
wheel.src = "wheel. png"; 
wheel. onload = function() { 

wheelOffset = wheel. width * 0.5; 

}; 

setlnterval(animatej 20); 

}); 
})(); 

The result is shown in Figuře 7-10. Wall<ing through the functionality of this code, we 
can see the following significant details: 

■ We add a drawWheel function that is responsible for rotating the 
canvas around a particular point and then drawing the wheel image so 
that it is centered on that point. We use the same technique that we 
used in the earlier rotation sample— we translate the origin of the 
canvas to the center point where the wheel was drawn, apply the 
rotation, and then call drawimage to draw the wheel image at the 
appropriate position. 

■ Inside the animate function, we calculate the angle that we shouid 
rotate the wheel by. We do this by applying the same tween function 
that we are using to animate the x position of the car image. This 
means that the wheels move in syne with the car. The example uses 
the PROWEBAPPS.Easing.Back.Out, but, ifyou chose not to implement 
any additional easing equations, you can obtain the required source 
code from the GitHub repository, at 

http : //github . coíti/sidelab/prowebapps - 

code/blob/master/js/prowebapps. js. Alternatively, feel free to use one 
of the easing equations implemented earlier if that is preferred. 

■ The drawWheel function is called twice in the animate function— once 
for each wheel. 

■ In startCar (which is essentially the functionality that used to be 
contained within the touchstart handler), a variable called endAngle is 
initialized. This variable is used in the wheel-easing calculation, and is 
set relative to the distance of the x position that we are sending the car 
to. By calculating this value relative to the end position of the car, the 
wheels move at a speed appropriate for the distance that the car has 
to move. 

■ Finally, the wheel image is loaded after the car image. For the wheel 
image load, we attach an onload handler so the wheelOffset can be 
calculated for an accurate wheel-imaging position in the drawWheel 
function. 
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Figuře 7-1 0. Animating the wheels provides a convincing animation. 
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NOTE: As per previous notes regarding strange behavior in Android 2.1 and canvas drawing, the 
rotated wheel does not appear correctly for that version. Every other version of Android is fine. 
Wliile we iiave shown you some tecliniques on liow to combat the oddities of 2.1 in your 
application code, if it is possible, then it wouid be wise to recommend users use Android 2.2 or 
greater for any web applications that make use of the HTIV1L5 canvas. 

The adoption of Android 2.2 is accelerating, and since we initially wrote the contents of this 
chapter (at which time 2.1 was the dominant version) 2.1 now runs second in usage to 2.2 (as at 
January 4, 201 1 Android 2.2 is installed on 51 .8 percent of devices, and 2.1 is now at 35.2 
percent). You can keep an eye on Android OS version distribution ratio at the following uri: 
http://developer.android.com/resources/dashboard/platform-versions.html. 

While we considered removing the content on the "tweaks" that were required to deal with the 
inadequacies of 2.1 , we felt that content still offered value to those of you who might have to 
deal with 2.1 during your mobile web application development. If you are in that group, then our 
thoughts are with you — good luck. 



Summary 

In this chapter, we covered a lot of materiál and samples focused on the HTML5 canvas, 
and looked at how we can use a combination of touch events and animation to create 
some Interactive démos. Hopefully, by exploring some of the functionality that is 
available with the HTML5 canvas, you have seen some potential for using this 
interactivity in your own applications or simple mobile games. 

We will work with the canvas again before the end of the book, but in the next chapter 
we will start to explore mobile mapping and location-based services. This will provide a 
basis for building a mobile game that uses elements of mapping, interactivity, and 
geolocation. There is a lot to learn, but iťs going to be a lot of fun doing it. 




Location-Based Services 
and Mobile Mapping 

The focus of the next four chapters will be on location-based services and building a 
geosocial game utilizing data from the geosocial network Gowalla (http://gowalla.com). 
If the terms location-based service and geosocial network mean little to you now (or if 
you've nevěr heard of Gowalla), don't worry— they will be explained very soon. 

As far as coding in this chapter, we will be looking at a couple of different mobile- 
friendly mapping APls (Google Maps and TileS) and how to render a simple map using 
them. We will then go deeper into the Google Maps API and look at how to display 
markers and interact with the map. While it wouid be great to do this with both Google 
and TileS, we really need to focus on a single solution to get through all the content. 
Additionally, Google presently provides one of the most robust mapping solutions for 
mobile, SO it makes sense to use its API in this book. 

Location-Based Services 

The term location-based service is generally used to define an information service that 
provides data based on geographical position (see 

http://en.wikipedia.org/wiki/Location-based_service for more information). 
Location-based services have risen in popularity recently and will contlnue to do so as 
more consumers acquire location-aware mobile devlces. 

One excellent example of using a location-based service is searching for an ATM 
(automated teller machine) that is close to your current location. Figuře 8-1 shows an 
example of the native Google Maps application on Android showing that kind of 
information. 
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Figuře 8-1 . Google Maps providing nearbyATM locations is one example ofa location-based service. 



Another example is an application called Urbanspoon (www.urbanspoon.com), which 
offers information on restaurants, including user reviews. A mobile screen capture from 
the Urbanspoon application "Near Me" feature is shown in Figuře 8-2. 
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Figuře 8-2. Urbanspoon offers restaurant suggestions for nearby locations, complete with userratings. 
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An interesting point about the Urbanspoon application is that, while the application is 
deployed as a native app, both of the results screens shown here were pulled down 
from the Web and embedded into the native application using a WebView (see 
littp://developer.android.com/reference/android/webl<it/WebView.litml). This is a 
similar technique to what we will be lool<;ing at in the next chapter using PhoneGap (see 
littp : //phonegap . com), and is an excellent way to deploy an application to the Android 
marl<etplace while still using web technologies for building most of the application. 

There are many more examples of location-based applications available both on the 
Web and in the Android marl<etplace. 

Geosocial Networking 

Geosocial networks (see http://en.wikipedia.org/wiki/Ceosocial_networl<ing for 
more info) have started to evolve over the last couple of years; they're essentially a result 
of the combination of location-based services and sociál networks (see 
http://en.wikipedia.org/wiki/Social_network for more on sociál networks). The 
current geosocial networks have far fewer participants than the leading sociál networks, 
but with the rollout of Facebook Places (www.facebook.com/places) geosocial networking 
is starting to hit the online mainstream. 

Geosocial networking currently revolves around the concept of check-ins. A check-in is 
basically where a user telis the geosocial network that they are at a particular pláce, 
spot, or venue (different geosocial networks use different terminology). In addition to 
registering that they are at a particular pláce, a user can also perform other actions that 
are associated with the venue. Depending on the sociál network, tips, tasks, or photos 
can be left by a user for others on the geosocial network to see. 

A very interesting part of geosocial networks is the way in which the real worid and 
Virtual worId interact. For instance, most sociál networks give rewards to users for 
regular check-ins or for having the most check-ins for a particular pláce (Foursquare 
calis the person with the most check-ins the mayor). Some businesses that have 
registered as places in the geosocial networks can then use those geosocial rewards to 
provide discounts to regular customers. This in turn incentivizes geosocial network users 
to regularly visit and check into venues, and also to participate in the geosocial network. 

Figuře 8-3 shows the screen captures from two major geosocial networks: Foursquare 
and Gowalla. 
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Figuře 8-3. Foursquare and Gowalla are two of the larger geosocial networks. 



A core concept in geosocial networks is tínat tine locations (places, spots, or venues) are 
user contributed. For instance, if while using Foursquare you went to a new restaurant 
and wanted to check in tinere, but couldn't find it in the list of places, you couid create it, 
winicin wouid allow both you and others to check in at that location. Using this technique, 
a geosocial network with an active community can quickly gather a large list of places. 

Hopefully that provides some background infornnation on both location-based services 
and geosocial networking. Leťs now get back to coding using some maps. 



Mobile Mapping 

While there are quite a few different JavaScript mapping APls available, very few of 
those have been optimized for (or even work on) mobile devices. At the time of writing, 
the primary thing that is lacking in most of the existing mapping APls is touch support 
for mobile devices. Thankfully, this is not the oase with the Google Maps API, so we will 
be able to run through some sample code using that API. 

In this section, we will have a look at implementing mobile maps for both Google Maps 
and a fairiy new HTML5 mapping API called TileS (www.tile5.org). For both APls, we will 
walk through the process of displaying a simple map, and then we will go on with the 
Google API to work through some samples in more detail. 




Displaying a Map with Google Maps 

Getting started with Google Maps is very simple. The following code sample (adapted 
from the Google Maps V3 JavaScript Tutoriál, at 

http://code.google.com/apis/maps/documentation/javascript/tutorial.html) 
demonstrates just how easy it is: 

<!DOCTYPE html> 

<html> 

<head> 

<title>Simple Google Map | Pro Web Apps</title> 

<meta name="viewport" content="width=device-width; initial-scale=l.O; maximum- 
scale=l.O; user-scalable=0; " /> 

<link rel="stylesheet" media="screen" href=". ./. ./css/proui.css" /> 
<style type="text/css"> 
html { height: 100% } 

body { height: 100%; margin: Opx; padding: Opx } 
</style> 

<script type="text/javascript" src=" . ./. . /js/jquery-l.4.2.min. js"></script> 
<script type="text/javascript" src=". ./. ./js/prowebapps. js"></script> 
<script type="text/javascript" 
src="http: //maps. google. coin/maps/api/js?sensor=false"></script> 

<script type="text/javascript"> 
function initMapO { 

// set the map slze to be window height less the header 

$("#map_canvas") .height($(window) .heightO - $("#main hl").outerHeight() - 20); 

// initialize the map initial position to near Sydney Australia 
var latlng = new google. maps. LatLng(-34. 397, 150.644); 

// configure the default options 
var myOptions = { 

zoom: 8, 

center: latlng, 

mapTypeId : google . maps . MapTypeId . ROADMAP 

}; 

II create the map, attaching it to the map_canvas element 
var map = new google. maps. Map( 

document . getElementByld ( "map_canvas" ) , 

myOptions); 

} 

</script> 
</head> 

<body onload="initMap()"> 

<ul id="menu"> 
</ul> 

<div id="main" class="view"> 
<hl>Google Map Test</hl> 
<div id="map_canvas"></div> 
</div> 
</body> 
</html> 



The preceding code sample demonstrates just how little JavaScript is required to get a 
simple map displayed in a web app. Essentially, it is a three-step process: 

1. Include the Google Maps API in your web application. The required script is 
located at http://maps.google.com/maps/api/js, and takés a sensor parameter. 
In the sample, we passed through a value of falše for the sensor parameter, but, if 
we had detected the user's location using the Geolocation API as we did in 
Ghapter 6, we wouid have needed to pass this value through as true. 

2. Define a function to initialize the map. This function's primary purpose is to create 
a new instance of a google. maps. Map class. The constructor takés two arguments: 
first, the div that will contain the map once the map is created; and, second, an 
object of options that influence the map initialization. In the preceding sample, the 
map was instructed to go to zoom level 8, positioned at a latitude and longitude 
near Sydney, Australia, and showing the map with a "Road Map" style. 

3. Finally, hook the function (initMap) up to the onload event of the document body. 

Once that is all done (and combined with our standard boilerpiate template), a screen 
similar to Figuře 8-4 will be displayed. 
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Figuře 8-4. Displaying a mobile-friendly Google map is a simple exercise. 
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TileS: An Alternativě HTML5 Mapping API 

While in most cases the Google Maps API is the best choice for your application, there 
are times where it just isn't an option — perhaps due to licensing restrictions (you nnay 
want to display advertising otiner than Google ads) or a particular clienťs needs. One 
example of this wouid be a client that wants to use its own mapping server for maps— 
iťs more common tlian you might think. 

TileS (littp://tile5.org) is an open source JavaScript library being developed to 
provide a mobile device-friendly mapping solution tínat can support multiple map 
providers. Presently, the majority of mapping APls tle you to a particular map provider 
(OpenLayers— http://openlayers.org— is a notable exception on the desktop). For 
some users, this restriction is completely acceptable, while other users regularly need to 
work with different mapping services, and having to change between APls can be quite 
frustrating. This is where TileS on mobile, and OpenLayers on the desktop, come into 
their own. 

As TileS is targeted at modem smartphone devices (at the time of writing, Android 
support is in progress but not yet stable), it is able to make extensive use of HTMLS. 
While, at this stage, the use of HTMLS oniy provides an experience comparable with 
other non-HTMLS mapping APls, we are likely to see hardware-accelerated HTMLS 
canvas implementations soon, and that is going to make things very exciting. 

The following code sample shows the equivalent code required to display a simple map 
using TileS in a similar fashion to the previous example using Google Maps. For this 
example, TileS connects to the CloudMade (http : //cloudmade . com) mapping servers, 
which serve image tiles generated from OpenStreetMap data. If you aren't aiready 
familiar with the OpenStreetMap (http://openstreetmap.org) initiative, then iťs definitely 
worth taking a look at. In their own words, it is "a free editable map of the whole worid." 
Essentially, as users we have the ability to add and update Information on the map. In 
the same way that Wikipedia is an encyciopedia that is maintained by people all over the 
worId, OpenStreetMap is a street map and atlas with many maintainers. 

<!DOCTYPE html> 

<html> 

<head> 

<title>Simple TileS Map | Pro Web Apps</title> 

<meta name="viewport" content="width=device-width; initial-scale=l.O; maximum- 
scale=l.O; user-scalable=0; " /> 

<link rel="stylesheet" media="screen" href=". ./. ./css/proui.css" /> 
<style type="text/css"> 
html { height: 100% } 

body { height: 100%; margin: Opx; padding: Opx } 
</style> 

<script type="text/javascript" src=". ./. ./js/jquery-l.4.2.[nin. js"></script> 

<script type="text/javascript" src=". ./. ./js/prowebapps. js"></script> 

<script type="text/javascript" 
src="http://www.tile5.org/jsapi/0.9.l/tile5. js"></script> 

<script type="text/javascript" 
src="http://www.tile5.org/jsapi/0.9.l/tile5.osm. js"></script> 




<script type="text/javascript" 
src="http://www.tile5.org/jsapi/0.9.l/tile5.cloudmade. js"></script> 

<script type="text/javascript"> 
function initMapO { 

// set the map size to be window height less the header 

$("#map_canvas") 

. attrC height 'j ($(window) .height() - $("#main hl") .outerHeight() - 20)) 
.attr( ' width ' , $(window) .widthQ - 15); 

var map = new T5.Map({ 

Container: 'map_canvas' , 
provider: new T5.Ceo.Cloudmade.MapProvider({ 
apikey: "I3077497529148b0a40flbf71728dl25" 

}) 

}); 

map.gotoPosition(new T5.Ceo.Position(-34.397, 150.644), 8); 

} 

</script> 
</head> 

<body onload="initMap()"> 

<ul id="menu"> 
</ul> 

<div id="main" class="view"> 
<hl>Tile5 Map Test</hl> 
<canvas id="map_canvas"></canvas> 
</div> 
</body> 
</htrtil> 

The implementation of this sample is very similar to the previous Google Maps example: 

1. The TileS library files are included from the TileS site. First, the oore tiles. js 
library is included, and this provides the generic functionality for mapping. We 
then include two additional files, tiles.osm. js and tile5.cl0udmade.js, which 
provide the code required to taik to CloudMade and other OpenStreetMap-based 
Services. 

2. A function is defined to initialize the map. In TileS, this involves first creating a 
Ts.Map instance and informing it of the HTML5 canvas element that it will attach 
to, and also informing the provider that will be used to supply the map tiles. Once 
a map instance is created, the gotoPosition method is called, instructing TileS to 
draw a map at a particular latitude and longitude for a zoom level. 

3. As per the Google example, the initMap function is called in response to the body 
onload event. 

This generates a screen like the one shown in Figuře 8-S. 
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Figuře 8-5. The TileS mapping API provides an HTMLS-based mobile mapping solution. 



While TileS is showing a lot of promise, it still hasn't reached a point winere Android 
support has been fully implemented and tested. Even though HTML5 Inas been used, 
tinere are still certain nuances tínat require tweaking to ensure the library belnaves weil on 
both iOS and Android; and up until now the primary focus has been iOS compatibility. 
For this reason, the application that we will build over the next few chapters will be bulit 
using Google's more mature API. As the TileS library matures, however, it is likely to 
provide one of the best alternatives to Google Maps for Android web apps. 

NOTE: The TileS library is a product being actively developed by Sidelab (www.sidelab.com). 
As I (Damon Oehiman) am tiie founder of Sidelab in addition to one of the authors of this book, I 
think iťs oniy fair to be open as to my involvement. 



Adding Markers to a Google Map 

One of the main reasons that you will have for implementing a map is to draw attention 
to nearby locations. Earlier in the chapter, we considered the specific example of 
showing nearby ATMs on a map, and in this and other situations placing graphical 
markers are an excellent way of communicating this. 

The code to add a marker to the map is also very simple, as demonstrated in the 
following code sample. With the following code, simply replace the initMap function in 
the previous sample with the updated function contents: 




<script type="text/]avascrlpt"> 
function initMapO { 

// set the map size to be window height less the header 

$("#map_canvas") .height($(window) .heightO - $("#main hl").outerHeight() - 20); 

// initialize the map initial position to Sydney Australia 
var latlng = new google. maps.LatLng(-34. 397, 150.644); 

// configure the default options 
var myOptions = { 

zoom: 8, 

center: latlng, 

mapTypeId: google. maps.MapTypeld.ROADMAP 

}; 

// create the map, attaching it to the map_canvas element 
var map = new google. maps.Map( 

document . getElementByld ( "map_canvas " ) , 

myOptions); 

// create a new marker to and display it on the map 
var marker = new google. maps.Marker({ 

position: latlng, 

map: map 

}); 

// capture touch click events for the created marker 
google. maps.event.addListener(marker, 'click', function() { 
alert ( ' marker dicked ' ) ; 

}); 

} 

</script> 

The preceding code performs two functions: 

1. First, a new marker is defined by creating an instance of a google. maps. Marker 
class. This is initialized by providing both the position of the marl<er and the map 
the marker will be added to. Once created, the marker will appear on the map. 

2. Next, we add an event listener to respond to click events for that marker. In the 
preceding samples, we simply displayed an alert to confirm that the event had 
fired. 

Once this has been completed, screens similar to the ones shown in Figuře 8-6 will be 
displayed. 
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Figuře 8-6. Adding a marker to the Google map draws attention to a location. 



We'll next have a look at something more intelligent than just showing an alert when the 
marker is clicked. 



Showing Marker Detail 

If you have had experience building desktop web applications and sites that incorporate 
Google Maps, then you will probably aiready be thinking ahead to displaying an info 
window for the marker. While this is very simple to do, it isn't a typically good fit for 
mobile maps, as demonstrated in Figuře 8-7. 
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Figuře 8-7. l/Wj/te great for desktop mapping apps, the info window isn't weil suited to mobile web apps. 



While not required, if you are interested in seeing the results for yourself, here is the 
code that corresponds to the screenshot displayed in Figuře 8-7: 

function initMapO { 

// set the map size to be window height less the header 

$("#map_canvas") .height($(window) .heightO - $("#main hl").outerHeight() - 20); 

// initialize the map initial position to Sydney Australia 
var latlng = new google. maps. LatLng(-34. 397, 150.644); 

// configure the default options 
var myOptions = { 

zoom: 8, 

center: latlng, 

mapTypeId : google . maps . MapTypeId . ROADMAP 

}; 

// create the map, attaching it to the mapcanvas element 
var map = new google. maps. Map( 

document . getElementById( "mapcanvas" ) , 

myOptions); 

// create a new marker to and display it on the map 
var marker = new google. maps. Marker({ 

position: latlng, 

map: map 

}); 

// create a simple info window 

var infowindow = new google. maps. InfoUindow({ 




content: 'Demo info window' 

}); 

// capture touch click events for the created marker 
google. maps.event.addListener(marker, 'click', function() { 
infowindow.open (map, marker); 

}); 

} 

While it is all weil and good to taik about how not to display marker detail, obviously this 
doesn't help us build a mobile web app that includes mobile mapping. So leťs have a 
look at some alternativě possibilities: 

■ We couid take the user to a detail page for that marker as soon as iťs 
tapped. 

■ We couId try to create a smaller custom info window that takés up less 
screen real estate and doesn't require a Close button— the window 
wouid automatically close when another pin has been tapped. 

■ We couId rework the interface to display marker detail at either the top 
or the bottom of the display, and perhaps provide a More Details 
button to take the user to the full detail page for the marker. 

Given these options, the third one is probably the best, so we will go with that option 
and see what can be done to restructure the interface and provide a foundation to move 
forward with our application build. 

A Mobile-Optimized Mapping Ul 

In this next section, we will work through the process of creating a Ul for mapping that is 
optimized for a mobile device. All the building blocks that we require are supplied in the 
Google Maps toolbox. Iťs just a case of being a little more selective with what we use 
than we might ordinarily be with a desktop application. 

A Mapping Ul Mocicup 

Before we get into the code for our mobile mapping Ul, we will begin by putting together 
a Ul mockup, as we did for our to-do list application in Chapter 4. This is displayed in 
Figuře 8-8. 




Figuře 8-8. A mockup of our optimized Ul for mobile mapping 

There are six primary components to the interface: 

1. The application title bar. We have gone back to the simple title style for this 
application as it is better suited to work with a full-screen map, and we really 
don't want to waste pixels with such limited screen real estate. 

2. The currently selected marker title. This bar is displayed when a marker is tapped, 
and shows the title of the tapped marker. The active marker is shown in element 
4. Depending on the application, tapping the actual marker title couid be used to 
take the user to a detailed Information page for the selected marker. In this case, 
the title shouid probably be underlined to indicate that it is also a link. 

3. Marker change selection navigation controls. These navigation controis are 
included to provide an alternativě mechanism for navigating through the markers. 
Instead of having to tap individual markers, the navigation controls can be used to 
move through the markers and change the active marker selection. 

4. The active marker. This is the marker that was most recently tapped or that has 
been navigated to with the navigation controls. 

5. An inactive marker. Inactive markers are displayed in gray, while the active marker 
is displayed in blue. 
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6. The zoom controls. These are provided by the Google Maps API for Android, as 
Android does not support multitouch events in the web browser at present. If you 
were to load the display on an iPhone, the zoom controls wouid not be displayed; 
however, other devices with a similar single-touch limitation wouId be likely to 
display the controls also. 

No work will be required on our part to have these zoom controls display, but it is 
important to remember that they are displayed at the base of the map, and thus that 
part of the screen is accounted for. 



NOTE: The preceding Ul has been designed with fingers in mind. When designing a mobile Ul, it 
is important to remember that your users will not be using the pixel-accurate selection of a 
mouše cursor. Rather, they will be using their fingers, which at their most accurate probably 
have a contact surface of about 10 pixels. If, as in the preceding mapping interface, it is possible 
that tappable elements will be in close proximity to one another (the markers in our case), think 
about providing alternativě Ul mechanisms to avoid causing your users frustration. 



Coding a Boilerpiate Mobile Mapping Ul 

With a clear understanding of the application Ul that we want to create, leťs now take a 
look at the code that is required to pull the interface together. 

First, here's the HTML code that is required: 

<!DOCTYPE html> 

<html> 

<head> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 
<linl< rel="stylesheet" media="screen" href="mapapp.css" /> 
<script type="text/javascript" src=". ./. ./js/jquery-l.4.2.tnin. js"></script> 
<script type="text/javascript" src="mapapp. js"></script> 

<script type="text/javascript" src=" http: //maps. google. com/maps/api/js?sensor=false"> 
</script> 

<script type="text/javascript"> 
function initializeQ { 

var latlng = new google. maps. LatLng(-34.397j 150.644); 

MAPAPP.init(latlng, 8); 

MAPAPP.addMarl<er(latlngj 'Test Marl<er', 'Some test contenť); 
} // initialize 
</script> 
</head> 

<body onload="initialize()"> 

<hl class="simple f loating">Mapping App Boilerplate</hl> 
<div id="map_canvas" style="width:lOO%; height:lOO%"></div> 
<div id="marl<er-nav"> 

<img src=" . . /. ./img/navigation-arrow.png" class="left disabled" /> 

<span class='marl<er-title'>Test Text</span> 

<img src=". ./. ./img/navigation-arrow.png" class="right" /> 
</div> 



<div id="marker-detail" class= child-screen > 

<div class='contenť>Some Test Content</div> 

<button class= ' close ' >Close</button> 
</div> 
</body> 
</html> 

The preceding HTML is simply a modified version of the HTML that we used before to 
demonstrate a simple Google Maps interface. We have, however, moved the iniine CSS 
and JavaScript into separate files and wrapped the JavaScript in a module called 
MAPAPP. This means the previous body of the initialize function is now largely 
encapsulated within the I^APAPP.init function. In this case, the initialize function 
simply initializes the map at the specified position (and zoom level) and then adds a 
simple test marker. 

To get the actual page displaying in a similar way to our mockup (Figuře 8-8), we also 
need to create a mapapp.css stylesheet that will contain our required CSS rules: 

/* apply the standard css recommended in GMaps tutoriál */ 
html { 

height: 100% 

} 

body { 

height: 100%; 
margin: Opx; 
padding: Opxj 
overflow: hiddenj 
font-family : Arial; 

} 

#iTiap_canvas { 
height: 100% 

} 

/* title styles */ 
hl. simple { 

font-size: 0.9em; 

padding: 8px 4px 4px 8px; 

background: #333333; 

color: #AAAAAA; 

border-bottom: 2px solid #AAAAAA; 
margin: O O 4px 0; 

} 

hl.floating { 

position: absolute; 
width: 100%; 
z-index: 100; 

} 

/* marker navigation bar */ 
#marker-nav { 

/* set generál color and style */ 

background: rgba(33, 69, I23j 0.8); 

color: white; 
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font-weight: bold; 

text-shadow: ipx ipx ipx rgba(50j 50, 50, 0.85); 
text-align: center; 

/* initialize positioning and layout */ 

position: absolute; 

top: 20px; 

z-index: 90; 

width: 90%; 

margin: O 2%; 

padding: l8px 3% lOpx; 

/* add the 'mandatory' border rádius */ 
border: 2px solid rgba(255, 255, 255, 0.2); 
-webkit-border-radius: I2px; 



/* marker navigation elements styling */ 
ftmarker-nav img.left { 
float: left; 

-webkit-transform: rotate(l80deg); 

} 

#marker-nav img.right { 
float: right; 

} 

#marker-nav img.disabled { 
opacity: 0.25; 

} 

ftmarker-nav span.has-detail { 
text-decoration: underline; 

} 

The preceding code can essentially be broken down into four sections: 

1. First, we have the recommended core CSS from the basic Google Maps Hello 
World tutoriál. This code sets the containing elements and the map container to 
fill the device screen. Note that additional CSS instruction has been added here 
(overflow: hidden) to assist with displaying detail views later in the chapter. By 
applying the overflow: hidden CSS, we can hide elements offscreen and not 
have scrollbars show for the window. 

2. Next, we provide some CSS that instructs an hl header element with the class of 
simple to be rendered using an absolute position and appear with the look and 
feel of the simple header style that we defined back in Chapter 2. Note also that a 
z-index CSS rule has been specified to instruct the hl element to display above 
the map. Without this instruction, the header wouid not be visible. 




3. We then apply some look-and-feel styling for the #marker-nav element. Once 
again, absolute positioning is used to ensure that the navigation bar plays nicely 
with the Google map, which is set to occupy the entire screen. Note the use of 
percentage positioning in the width, padding, and margin CSS rules. Using 
percentages here provides the best possible chance of our mapapp template 
working with varying screen sizes. 

4. Finally, we have some CSS rules for displaying the navigation buttons and having 
them align correctly inside the navigation menu. Additionally, here we see the 
webkit-transform CSS3 rule being used (as in Chapter 6 for the loading spinner) 
to enable us to reuse the same basic navigation arrow image but display it rotated 
180 degrees. 

All that is required to complete the display is to incorporate the very simple JavaScript 
Google Maps display logic from earlier into its own file, mapapp. js, and wrap this using 
the JavaScript module pattern so we can build a larger application on it. 

MAPAPP = (functionO { 

// initialize constants 
var DEFAULT_ZOOM = 8; 

// initialize variables 
var map = null, 
markers = []; 

function addMarker(positionj title, content) { 

// create a new marker to and display it on the map 
var marker = new google. maps. Marker({ 

position: position, 

map: map, 

title: title 

}); 

// add the marker to the array of markers 
markers . push (marker) ; 

// capture touch click events for the created marker 
google. maps. event.addListener(markerj 'click', function() { 
// update the navbar title using jOuery 
$( '#marker-nav .marker-title' ) .html(marker.getTitle()); 

}); 

} // addMarker 

var module = { 

addMarker: addMarker, 

init: f unction(position, zoomLevel) { 
// define the required options 
var myOptions = { 

zoom: zoomLevel ? zoomLevel : DEFAULTZOOM, 

center: position, 

mapTypeControl: falše, 

streetViewControl: falše, 

mapTypeId : google . maps . MapTypeId . ROADMAP 



// initialize the map 

map = new google. maps.Map( 

document .getElementById("map_canvas"), 

myOptions); 



} 



}; 



return module; 



})(); 



In the preceding code, we separate the previously combined functionality into two 
functions: APPMAP.init and APPMAP.addMarker. This will give us an excellent base from 
which to implement the extended functionality in the next section (adding multiple 
markers and viewing marker detail). 

With that last piece of the initial boilerpiate code in pláce, an interface similar to the one 
displayed in Figuře 8-9 shouid be displayed. The oniy real difference between the 
preceding JavaScript and the earlier sannples is that this one uses jQuery to update the 
navbar title with the title of the marker in response to the marker being clicked. 
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Figuře 8-9. With everything going to pian, our actual layout will be displayed much like our mockup. 



Implementing Ul Navigation in the Boilerpiate 



With the interface laid out as required, we will now flesh out other parts of our 
application interface. First, we will make some simple modifications to the HTML to 

include a child view div that will provide us with the abllity to select a marker, tap the 
marker title, and get more infornnation on that location. 

The modifications to the mapapp.html are as follows: 

<IDOCTYPE html> 
<html> 

<div id="marker-nav"> 

<img src=". ./. ./img/navigation-arrow.png" class="left disabled" /> 

<span class='marker-title'>Test Text</span> 

<img src=". ./. ./img/navigation-arrow.png" class="right" /> 
</div> 

<div id="marker-detail" class="child-screen"> 
<div class= ' contenť >Sotne Test Content</div> 
<button class= ' close ' >Close</button> 

</div> 

</body> 
</htiiil> 

The marker-detail div is added just before the end of the body tag, and just after the 
marker-nav div that we created earlier. Making these changes to the HTML will break 
the map display, and the following additional CSS rules are required to bring everything 
back to displaying correctly. Add the following CSS to the end of the mapapp.css file: 

div.child-screen { 

background: rgba(255, 255, 255, 0.75); 
width: 100%; 
height: 100%; 
left: 100%; 
top: Opx; 

position: absolute; 
z-index: 91; 

} 

div.child-screen .content { 
margin: 50px lOpx 0; 

} 

div.child-screen button. close { 
height: 30px; 
position: absolute; 
bottom: lOpx; 
left: lOpx; 
right: lOpx; 
display: block; 

} 

Notice that the CSS rules specify that a div of class child-screen will be displayed with 
absolute positioning and have a height and width of 100%. This means that these div 
elements, like the map, will take up the entire screen when displayed. What stops this 
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screen from displaying when the HTML is first rendered is the absolute left position 
specified at 100% (shown in bold). 

This works in conjunction witin tine overflow: hidden CSS from tine previous code to 
hide tine div off the right side of tine nnap until we need it. 

When we require the child-screen div to display, we dynamically set the left position of 
the div to Opx. In terms of visual styling, we apply a baci^ground fill using the rgba CSS 
function to display a slightly transparent white bacl<;ground. This provides a nice visual 
effect, in which the map is still slightly visible under the child screen that has been 
activated. The z-index of 91 places it above the HTML elements on the map screen, but 
beneath the hl title. 

Finally, make the following modifications to the mapapp. js file to properly activate the 
navigation flow: 

MAPAPP = (functionO { 

// initialize constants 
var DEFAULT_ZOOM = 8; 

II initialize variables 
var map = null, 

mainScreen = true, 

markers = W, 

markerContent = {}j 



function activateMarker(rtiarker) { 

// update the navbar title using jOuery 
$('#marker-nav .marker-title' ) 

. html (marker . getTitle( ) ) 

.removeClass( ' has-detail' ) 

.unbindC click' )\ 

II if content has been providedj then add the has-detail 

// class to adjust the display to be "link-like" and 

// attach the click event handler 

var content = markerContent [marker .getTitle() ] ; 

if (content) { 

$( '#marker-nav .marker-title') 
.addClass( ' has-detail ' ) 
.click(function() { 

$( '#marker-detail .content' ) .html(content); 
showScreen( 'marker-detail' ); 

}); 

} // if 
} // activateMarker 

function addMarker(positionj title, content) { 

// create a new marker to and display it on the map 
var marker = new google. maps.Marker({ 

position: position, 

map: map, 

title: title 

}); 



// save the marker content 
markerContent[title] = content; 

// add the marker to the array of markers 
markers . push (marker) ; 

// if the first marker, activate automatically 
if (markers. length === l) { 

activateMarker (marker, content); 
} // if 

// capture touch click events for the created marker 
google. maps.event.addListener(marker, 'click', function() { 

// activate the clicked marker 

activateMarker (marker); 

}); 

} // addMarker 

function initScreenO { 

// watch for location hash changes 
setInterval(watchHash, 10); 

// next attach a click handler to all close buttons 
$( ' button. close' ) .click(showScreen); 
} // initScreen 

function showScreen(screenld) { 

mainScreen = typeof screenid !== 'string'; 
if (typeof screenid === 'string') { 

$('#' + screenid). css('lefť, 'Opx'); 

// update the location hash to marker detail 
window. location. hash = screenid; 

} 

else { 

$( ' div. child-screen ' ) . css ( ' lef t ' , ' 100% ' ) ; 
window. location. hash = ''; 
} // if..else 

scrollTo(0, l); 
} // showScreen 

function watchHashO { 

// this function monitors the location hash for a reset to 
if ((! mainScreen) && (window. location. hash === '')) { 

showScreen(); 
} // if 

} // watchHash 

var module = { 

addMarker: addMarker, 

init: f unction(position, zoomLevel) { 



// initialize the screen 
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initScreenO; 

} 

}; 

return module; 

})(); 

In the preceding code, the showScreen function does most of the legwork. When it is 
passed a string parameter (which it checks for using the JavaScript typeof operátor), it 
uses jQuery to bring that HTML element into view by adjusting its left position. This 
works in conjunction with the previously defined CSS to bring in and hide separate 
views in the main application viewing area. To the end user, this provides a similar 
experience to what we coded in the earlier to-do list application. In this case, however, 
we are using absolute positioning based on the presence and requirements of the map 
component. 

Another notable part of the code is the watchHash function, which is called at regular 
intervals (courtesy of the JavaScript setinterval function). The purpose of the function 
is to monitor the window. location . hash property and keep the application Ul in syne. 
This means that the user will be able to use the back button on the browser, in addition 
to the Close button, which is placed in a child view to navigate back to the main screen. 

Finally, we update the addMarker function to save the marker content into the 
markerContent object for each of the marker titles, and also call a new function 
(activateMarker) when a marker is clicked — rather than simply updating the title. At first 
glance, the activateMarker code may appear a little complicated, but iťs reasonably 
simple once you break it down: 

1. First, HTML elements with the marker-title class are updated with the title of the 
marker (retrieved using the marker. getTitle method). At the same time, the has- 
detail class is removed, and we unbind the click event handler, as the marker 
may not actually have any content and therefore no detail screen. The has-detail 
class was defined in the previous section's boilerpiate CSS to simply show an 
underline under the text, thereby simulating a link. 

2. Second, if the marker has content associated, then we add the has-detail class 
and bind a click handler to the marker title. Now, when the user clicks the marker 
title, they will be taken to the marker-detail screen and shown the HTML content 
that was specified for the marker. 

With these modifications complete, we will be able to navigate to our placeholder child 
view by clicking the marker title that will be displayed underlined in the navigation bar. 
Figuře 8-10 illustrates this. 
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NOTE: You might be wondering why we are reimplementing functionality that we have aiready 
covered in our previous to-do list application. This is because the navigation code we 
implemented as part of our to-do list application doesn't work weil with the recommended 
Google Maps layout. Rather than attempt to retrofit the code to suit the Google IVIaps code, it was 
a simpler exercise to create a separate mapping application boilerpiate. 



As mentioned earlier in the bool<, the mobile web app space is crying out for a mature, mobile 
JavaScript framework that will take care of some of the grunt work that is involved with writing a 
mobile web app. 

There are aiready some good contenders out there, but Android and other mobile device support 
isn't very extensive yet. My money is definitely on jQuery Mobile in the long run. This will 
hopefully be released shortly before this book, but not at the time of writing unfortunately. 
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Figuře 8-1 0. We are now able to navigate to a subscreen by clicking the marker title in the nav bar. 



Selecting Markers with the Navigation Bar 

In this next section, we will populate the mapping display with a number of markers, and 
look at tweaking the boilerpiate mapping app code to allow us to select between 
markers using the navigation bar in addition to tapping the map. 



Setting Up the Markers and Showing Custom Icons 



This will require us to add a few additional markers to the test boilerpiate HTML code 
(mapapp.html) to ensure that the functionality works, so leťs do that now. Replace the 
contents of the initialize function in the page with the following script: 

function initializeO { 

var latlng = new google. maps. LatLng(-33.866j 151.209); 

MAPAPP.init(latlng, 13); 

MAPAPP.addMarker(latlngj 'Sydney', ' Sydney Australia ' ); 
MAPAPP.addMarker(new google. maps. LatLng(-33.859j 151.209), 'The Rocks'); 
MAPAPP.addMarker(new google. maps. LatLng(-33.857j 151.215), 'Sydney Opera House'); 
MAPAPP.addMarker(new google. maps. LatLng(-33. 861, 151.211), 'Circular Quay'); 
} // initialize 

This will add a total of four markers to the display. Without adding any additional code, 
this will create a display similar to the one shown in Figuře 8-1 1 . 



Figuře 8-1 1 . Four markers are displayed, two of which are in close proximity. 

Iťs now time to implement some icons for the markers rather than using the default 
indicators. This will allow us to use two separate icons and indicate to the user which of 
the markers is the currently selected marker. The two marker image files are pin- 
active.png and pin-inactive.png, and these can be downioaded from the img directory 
of the prowebapps-code repository (http://github.com/sidelab/prowebapps-code) on 
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GitHub. 



186 



CHAPTER 8: Location-Based Services and Mobile iVlapping 




The following code shows the modifications that are required to the addMarker and 
activateMarker functions to enable the use of a custom icon. When the first marker is 
added, this marker is automatically activated. 

function activateMarker(marker, content) { 

// iterate through the markers and set to the inactive image 
for (var ii = 0; ii < markers. lengthj ii++) { 

markers [ii] . setIcon( ' . ./. ./img/pin-inactive.png' ); 
} // for 

// update the specified marker 's icon to the active image 
marker. setIcon( ' . ./. ./img/pin-active.png' ); 



} // activateMarker 

function addMarker(position, title, content) { 

// create a new marker to and display it on the map 
var marker = new google. maps.Marker({ 

position: position^ 

map: map^ 

title: title, 

icon: ' . ./. ./img/pin-inactive.png' 

}); 

// add the marker to the array of markers 
markers . push (marker) ; 

II if the first marker, activate automatically 
if (markers. length === l) { 

activateMarker(marker, content); 
} // if 

} // addMarker 

With the preceding code modifications in pláce, it is now possible to distinguish 
between the currently selected marker and inactive markers. We will now be able to 
implement navigating through the markers in the next section. The map display shouid 
appear as shown in Figuře 8-12. 



UHe 4:22 PM 



4:25 PM 



Mapping App Boilerplate 



Mapping App Boilerplate 




Balmain 
^gg( MiHers Pomí 



Barangargg 'líV^^fít^J 

líiLind ^ . 



Bátanii:; 
larciflnfi 



Island 
Pymant 



i'!^" Sydnéy^potts Point 



« Ultimo S5wt, 



'9« Glebe 



3 s 



Elizabeth 
Bay 

Edge 



Haymarket 



Darlínghuret 
" PadiJingtor 



The University j BfDadway 
--or.syjin^.// chippendale -^kfc^, 



POWERED BV 



R&dfern 



-w—ifloore Part 



Part; 



Sydney Opera House [> 



Lavander (T) 'V „-. 
^ Bay lil 




Balmain 
^35) Millers Posnt 

Barangarao 



3 



Dořiťte 



pymont 



Sydneytpotts Point 



B Ultimo Oí„ft| 



(íl 



Elizabeth 
Bay 



Gleije 



Of Sydney , 

POWERED EV V^*^ 



I 

Haymarket f í Darlinghurít 
Chippendale 



Edge 



R&dfern 



Tf"ifloore Part 



Part; 



Figuře 8-1 2. M/ften řfte map is first displayed, the Sydney marker is active, but others can be selected by tapping. 



Implementing the Tapless Marker Selection 

Now that it is possible to distinguish between an active marker and an inactive one, it is 
time to implement the navigation controis to allow us to navigate through tine markers 
without having to tap individual markers. 

There isn't too much to this next section, as it is just a matter of keeping track of the 
activated marker's position in the marker array and updating the navigation controis 
accordingly. To do this, however, we will first need a utility function that will tell us a 
marker's position in the marker array. The following code defines a getMarkerIndex 
function that shouid be included in the mapapp. js code just before the initScreen 
function. 

function getMarkerlndex(marker) { 

for (var ii = 0; ii < markers. length; ii++) { 
if (markers[ii] === marker) { 

return ii; 
} // if 
} // for 

return -l; 
} // getMarkerIndex 

We then implement an updateMarkerNav function that will update the navigation button 
State. The ideál location for this function in the mapapp. js is just above the existing 
watchHash function. 



function updateMarkerNav(markerlndex) { 




// find the marker nav element 
var markerNav = $( '#marker-nav' ); 

// reset the disabled statě tor the irtiages and unbind click events 
markerNav. find( ' img' ) 

.addClass( 'disabled' ) 

.unbind( ' click' ); 

II if we have more markers at the end of the array, then update 
// the marker statě 

if (markerindex < markers. length - l) { 
markerNav. find( ' img.right ' ) 
.removeClass( 'disabled' ) 
.click(function() { 

activateMarker (markers [markerindex + l]); 

}); 

} // if 

if (markerindex > O) { 

markerNav.f ind( ' img.left ' ) 
.removeClass( 'disabled ' ) 
.click(function() { 

activateMarker(markers[markerIndex - l]); 

}); 

} // if 
} // updateMarkerNav 

As per the earlier activateMarker function, the first thing the updateMarkerNav function 
does is reset the navigation buttons to the default statě: disabled and with no click event 
handling. 

Then, based on the value of markerindex passed to the function, the navigation buttons 
are selectively enabled and click events bound. This will allow users of the application to 
navigate through markers without having to tap each one. We are not quite there yet, 
though, as our present logic is a little flawed in the addMarker function. Figuře 8-13 
shows the display after adding the four markers. 
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Figuře 8-1 3. Something isn't right here — we have our four pins but no navigation button. What gives? 



It turns out that navigation controis are displayed in response to tine marker being 
activated, and previously tinis was triggered wlien our marker was detected as tine oniy 
marker in tine list. Wliile tinis was fine before, we are now configuring Ul elements based 
on tlie number of markers, so this will have to be dealt witli slightly differently. 

Wliile tliere are a number of ways that we couid solve this particular problém, erring on 
the side of simplicity is probably best. In this oase, we can simply add another exported 
function (called updateDisplay) to the MAPAPP module: 

MAPAPP = (functionO { 



var module = { 



updateDisplay: function() { 

// if we have at least one marker in the list, then 
// initialize the first marker 
if (markers. length > O) { 

activateMarker(markers[o] ); 
} // if 

} 

}; 

return module; 

})(); 



With this new function in pláce, we can then remove the following lineš from the 
addMarker function: 




// if the first marker, activate automatically 
if (markers.length === l) { 

activateMarker (marker j content); 

} // if 

Finally, we add the MAPAPP.updateDisplayO call into the initialize function in 
mapapp.html: 

function initializeO { 

var latlng = new google. maps. LatLng(-33.866, 151.209); 

MAPAPP.init(latlng, 13); 

MAPAPP.addMarker(latlng, 'Sydney', ' Sydney Australia ' ); 
MAPAPP.addMarker(new google. maps. LatLng(-33. 859, 151.209), 'The Rocks'); 
MAPAPP.addMarker(new google. maps. LatLng(-33. 857, 151.215), 'Sydney Opera House'); 
MAPAPP.addMarker(new google. maps. LatLng(-33. 861, 151.211), 'Circular Quay'); 

// update the map display 
MAPAPP . updateDisplay ( ) ; 

} // initialize 

Now we have quite a functional set of boilerpiate files that we can use to build a mobile 
web-mapping application using Google Maps. However, before we move on to building 
our geosocial app in the next chapter, there is one finál tweak that shouid be made to 
polish things up slightly. 



Applying Sorting to Ensure Intuitive Marker Navigation 

Presently, the order in which the markers are navigated is the order they were added to 
the list. To someone using the app, this wouid likely appear fairiy random and not very 
intuitive. So, before we move on, leťs get those markers in some kind of logical sort 
order— ideally top to bottom and left to right. 

First of all, we will create a sortMarkers function that can take the markers and sort 
them in order of northwestern-most position to southeastern-most position. Ideally, this 
function shouid be just before the updateMarkerNav function, but this is not critical. 

function sortMarkersO { 

// sort the markers from top to bottom, left to right 

// remembering that latitudes are less the further south we go 

markers. sort (function(markerA, markerB) { 

// get the position of marker A and the position of marker B 
var posA = markerA.getPosition(), 
posB = markerB.getPosition(); 

var result = posB.lat() - posA.lat(); 

if (result === 0) { 

result = posA.lngO - posB.lng(); 
} // if 

return result; 

}); 

} // sortMarkers 
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The preceding code makes use of the built-in JavaScript sort function (see 
(https : //developer. mozilla.org/en/DavaScript/Reference/Global_Objects/Array/sor 
t). When using the sort function, you sinnply provide a comparison callback to the sort 
function that tal<es two parameters. 

This callback will then be executed with members of the array until the array is sorted 
according to the required order. To affect this sort order, sinnply return a value less than 
O if item A shouid occur earlier in the list than item B, and a value greater than O if the 
reverse is true. If the items are equivalent, simply return 0. 

With the sort function complete, we just need to modify the MAPAPP . updateDisplay 
function to incorporate the sorting: 

MAPAPP = (functionO { 



var module = { 



updateDisplay: function() { 
// get the first marker 

var firstMarker = markers.length > O ? markers[o] : null; 

// sort the markers 
sortMarkersO; 

// if we have at least one marker in the list, then 
// initialize the first marker 
if (firstMarker) { 

activateMarker (firstMarker) ; 
} // if 

} 

}; 

return module; 

})(); 

Essentially, the function is modified to first save the first marker in the array (as this is 
assumed to be the most important marker and shouid probably be the first selected) 
and then sort the markers. If an initial marker is saved, then this marker is activated. 
Figuře 8-14 shows the display after implementing the sort code and modified 
MAPAPP. updateDisplay function. 




HEBG 8:56 PM 



Mapping App Boilerplate 



Mílsons ' 
Róirrt. 




Point 



Bal mam 
^ggj MillersPoml 

^^^^ Barangaroo 
Island . 



0ř . 



est 
Ige 



Ultimo Gowtj, 



Elisabeth 
Bay 



'"""St 

Glebe Haymarket ^ Darlinghurst 



Edge 



The University ; Bruadway^/r" 
WSijún^í.,:' ctiippendale 



Paddington 




Figuře 8-1 4. Tfie mapping interface after sort logic has been applied. Sydney is still activated, but is now the last 
marl<er in the list based on its latitude and longitude. 



This brings us to the end of the boilerpiate mapping application code. Essentially, the 
three files (mapapp.html, mapapp.css, and mapapp. js) can now be taken and used as a 
template tor a mapping application that uses the Google IVIaps API. 



Summary 

This chapter covered a lot of materiál in the areas of mapping and location-based 
Services. We looked at two different mapping APls that are currently available, and 
looked in some depth at how to create a web-mapping application that uses the Google 
APls and feels good in the Android browser. 

Like most mobile web app development, this has involved being selective about the 
tools that we used and applying some different usability principles than might be used 
for building a desktop web application. 

In the next chapter, we will take this boilerpiate code and use it as the basis for our 
geosocial app. In addition to working through parts of the application, you will also get 
an introduction to PhoneGap as we wrap the web app in native code. By the end of the 
build, we'll have a product that can be deployed to the Android marketplace. 
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Native Bridging with 
PhoneGap 



In the previous chapter, we looked at working with mobile maps in preparation for 
writing our geosocial game. In this chapter, we will have a look at PhoneGap 
(http://phonegap.com) as a tool to assist us in deploying our web applications as native 
apps. This will give us the ability to deploy our applications to the Android marketplace, 
while letting us continue to build the core of the application using web technologies. 

We will investigate some very good reasons that we might want to do this in the next 
section. First, it will allow our geosocial game to give native applications a run for their 
money, and it will make it difficult for consumers to distinguish between a native app 
and a web application deployed as native. 

Essentially, we are going to be learning how to have our cake and eat it too— which in 
our opinion is aiways a good thing. 



PhoneGap is a framework/tool for packaging a mobile web application for native 
distribution. Additionally, frameworks like PhoneGap provide capabilities for pure web 
applications to access functionality of the mobile device. This is achieved by the native 
wrapper application providing a bňdge to the web application, and in the case of 
PhoneGap this is done using a JavaScript library (on the surface at least). 

PhoneGap is just one of many bridging frameworks. While the term bridging frameworl< 
isn't in wide usage at present, it does represent very weil what they are designed to do. 
At its core, PhoneGap is the purest of these frameworks, offering just the bare bones 
required to access the native features, without making any suppositions about other 
parts of your application build. 

Another bridging framework that is weil worth a look is a product from Rhomobile called 
Rhodes (http://rhomobile.com/products/rhodes). Rhodes provides an application 
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stack designed for building data-driven mobile web applications. If you are a user or fan 
of Rails (http://rubyonrails.org), then you are likely to find a comfortable fit witin 
Rhodes. 

One last framework that has gained quite a bit of attention (but wouldn't actually class 
as a bridging framework) is a product called Appcelerator Titanium 
(www.appcelerator.com). The Appcelerator approach is quite different from both 
PhoneGap and Rhodes. Rather than building an application that wraps a mobile web Ul 
with a simple native wrapper application, Appcelerator buiids a native app from 
JavaScript code. As more web-enabled mobile devices gain market share, this 
approach may show some limitations; however, it is worth a look all the same. 

In terms of where to start with all of these different options, PhoneGap is an excellent 
choice— which is why we are using it in the book. There isn't much that you can't do 
with PhoneGap, and you aiways have the choice of what you will mix and match with it. 
Most other solutions won't give you the same scope to explore. 

When to Use PhoneGap 

There are two basic situations that wouid justify the use of a bridging framework such as 
PhoneGap: 

■ When a mobile web application that you are writing needs access to 
device functionality not currently exposed through an implemented 
web API. A good example is accessing either the accelerometer or the 
camera. 

■ When you want to package the application for native distribution in the 
Android marketplace (or equivalent device app store). With the various 
mobile application stores being common places for people to look for 
their applications, this is something aiways worth considering. 

The second of these situations is probably the more common. One of the advantages of 
developing using PhoneGap (instead of another bridging framework) is that, even if this 
hasn't been considered when first writing a mobile web app, it is very simple to package 
an application with PhoneGap at a later stage. 

Downioading PhoneGap 

At the time of writing, the current stable release of PhoneGap is 0.9.3, which can be 
downioaded by going to the following URL and obtaining the release archive: 
www. phonegap. com/download. 

Once you have downioaded the ZIP file, extract it and pláce it where you normally keep 
your developer tools. The distribution contains a number of folders with template 
projects designed to help you to build and deploy mobile applications for a variety of 
platforms using PhoneGap. The files for Android are sensibly located in the Android 
directory. 



Cl 



■ phonegap-0.9.3. This is a Java archive containing the compiled 
classes that are used to make PhoneGap function on Android. If youYe 
interested in Inow pieces of PlnoneGap worl< (and you're comfortable 
reading Java source code), then you can have a \ook at tlie phonegap- 
android project on GitHub (http://github.com/plionegap/phonegap- 
android). Tliis is purely optional, tliough, as it is not required to build 
applications using PhoneGap. 

■ phonegap-0.9.3. js: This is the JavaScript file that provides the 
JavaScript stubs that manage the connmunication between the web 
application and the native wrapper. We'll tal<e a lool<; at some of the 
functionality offered by this JavaScript library later in the chapter. 

■ Sample: This is a sannple project directory. We will use it as a base for 
creating our application using PhoneGap, and in the next section we'll 
lool<; at the internals of the sample to gain an understanding of the 
capabilities of the PhoneGap framework. 

A Sample PhoneGap Application 

Now that we've downioaded PhoneGap, leťs create a copy of the sample application 
and get an understanding of what can be done using PhoneGap. In the directory that 
you are using for the samples in this book, create a directory called bridges. Then copy 
the Sample directory from the Android directory located within the PhoneGap downioad 
to that new directory. 

This will provide us with a skeleton PhoneGap native Android project in the 
bridges/Sample folder. The directory structure for this skeleton project is displayed in 
Figuře 9-1. 
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Figuře 9-1 . The Sample PhoneGap application folder has everything you need to get started. 

While we won't go into detail on all the various files and folders in our Sample directory, 
as most pertain to the native wrapper application, there are some that deserve furtlier 
explanation: 

■ AndroidManifest.xml: This file is used by the native Android 
application in a number of ways, including specifying what l<;ind of 
device permissions are required by the application and what classes 
are used to run the application. 

■ assets/www/: This directory contains the HTML, CSS, and JavaScript 
files that are included in the WebView of the PhoneGap native wrapper 
(see 

http : //developer .android . com/ref erence/android/webkit/WebView . h 
tmi for more about WebViews). In particular, notice the phonegap. js 
file here. This file needs to be included in your web pages to properly 
access PhoneGap's bridging functionality. We will look at this in more 
detail soon. 

■ libs/phonegap-0.9.3. This is the Java library that is used to build 
the native application. Without it, your application won't work (or 
build). 
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■ res/: This directory contains the various resources that are used by 
the native application. When it comes time to deploy your application, 
you will need to replace icon . png files in a few places under this 
directory so you aren't using tlie default PlioneGap icon. 

■ src/*: TInis directory contains tine application source files that are used 
to create the native executable for the wrapper application. 

■ build.xml: For building the native wrapper application, the Android 
SDK uses a Java build systém called Ant to build projects from the 
command line (see http://ant.apache.org). This build.xml file is 
essentially an instruction file that telis the Java SDK how to build an 
application. 

Thaťs pretty much it. While the other files are important and required to build the native 
wrapper, we really don't need to know what they do— our primary concern is with the 
web files that are embedded in the native app. Additionally, for the moment we will play 
with the sample application as is, but will work through which of the files in the sample 
application need to be changed when building an application of our own. 



Building tlie Sample Application 



Now that we have the sample application directory created, the next thing to do is work 
out how to build and run the native application in the Android emulátor. 

NOTE: As mentioned previously, Ant is used by the Android SDK to build native applications. 
you don't aiready have Ant installed on your systém, then you will need to obtain and install 
before you can go further in this chapter. Instructions for installing Ant on various systems ai 
available at http://ant.apache.org/manual/install.html. 

With Ant installed and available on your systém path, in a terminal window or at 
command prompt, change directory to the newly created sample directory, and execute 
ant with no command-line parameters to see the list of valid build targets. Figuře 9-2 
shows output generated from running the command. 




198 



CHAPTER 9: Native Bridging with PhoneGap 



Terminal — bash - lOOx-10 
O emulátor O 
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BUILD FAILED 
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Figuře 9-2. Attempting to build the sample project fails, as the path to the Android SDK is not yet known. 



Hmmm, that can't be right— we shouid have seen a more meaningful message than that. 
While the sample project is quite complete in terms of everything required to create a 
PhoneGap project, it doesn't know the location of the Android SDK, and as a result the 
Ant build fails. This can be rectified by using the android command-line tool (one of the 
core tools in the Android SDK; it was introduced in Chapter 1) to generate a 
local.properties file for the build. 

Simply run the following from the command line, with the copied sample directory as the 
current directory: 

android update project -p ./ 

This creates a local.properties file for the project that contains a single property, 
sdk.dir. This telis Ant where it can find the Android SDK, and consequently the required 
build tools to build the sample application. 

Attempting to run Ant again once the local.properties file has been created will 
generate output similar to that shown in Figuře 9-3. 
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Figuře 9-3. Running Ant with no command-line options provides information on liow to build, andalso validates 
that the build process is working correctly. 

Now that Ant is configured and working correctly, we can build our app. While a number 
of options are displayed, for the moment the following are of most interest: 

■ debug: The Ant debug target is used to build the application and sign it 
with a debug key. Once the application is built with the debug key, it 
can then be installed in the emulátor (or a device configured for 
development) and therefore run. 

■ install: The install target is used to copy the compiled executable 
to the emulátor or device. 

■ uninstall: Using the uninstall target in Ant will allow us to remove 
the application from either the emulátor or the device. This can be very 
helpful, as removing an application from a device otherwise takés 
quite a bit of mucking around. 

Now iťs time to build the app. First, you will need an emulátor or device connected for 
the install target to be able to run successfully. Run the following command from the 
command line to check that you have an emulátor or device that the app can be 
installed to successfully: 
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adb devices 

The adb command (which stands for Android Debug Bňdge) is one of the tools installed 
with the Android SDK. This particular command provides Information on the Android 
emulators and devices that are currently connected. Any Android device that is currently 
connected can then be interfaced with using a variety of developer tools. For more 
information regarding debugging Android web apps, see Appendix A. 

If you have a valid emulátor running, then you shouid see output similar to Figuře 9-4. If 
not, then you will need to start an emulátor instance or attach an Android device via 
USB. 



adb 



danioinac : sample damos adb devices 
Li^t of devices attached 
emulatDr-5554 device 

dafnoHiacz^ample dama$ [] 



Figuře 9-4. If an emulátor is running (or a device Is attached), then it wlll be shown by running "adb devices. " 



An emulátor can be started by following the instructions outlined in Chapter 1 . 
Alternatively, you can run the following command: 

emulátor @android_web_apps 

The emulátor executable is used to start the Android emulátor directly from the 
command line. You specify which of the Android Virtual Device (AVD) images to use by 
providing a single parameter that has the ID of the AVD image with an @ symbol 
preceding it. 
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TIP: While it is not mandatory to include the ANDROID_SDK/tools directory in your systém 
path, iťs definitely worthwhile. Being able to access the adb and emulátor commands without 
having to specify a full path will definitely save a lot of time. If you haven't aiready done so, then 
we'd recommend you do that now. 



Given that you now (if you didn't aiready) have an Android emulátor running or a device 
connected, you can run the build process to create a native Android application from the 
sample PhoneGap project and see how that looks. 

Run the following from the command line, with the created sample directory as the 
current directory: 

ant debug install 

This will instruct Ant to execute both the debug and install targets in the build. xml file. If 
the build process completes successfully, you will see the magie words "BUILD 
SUCCESSFUL" (see Figuře 9-5), and at this point you shouid be able to locate and run 
the sample PhoneGap application in your emulátor. 
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Figuře 9-5. Successful completion of the build and installation of the PhoneGap wrapper application 




If you see a message saying "BUILD FAILED," then unfortunately something has not 
gone to pian. In most cases, this will be related to the build process not being able to 
deploy the sample application to the emulátor or device. Retrace your steps and 
recheck the output of the adb devices command; you need to see a device listed in the 
output of this command, and its status shouid be shown as "device." If the emulátor is 
running but it is either not listed or is marked as "offline," then close and restart the 
emulátor and try again. 

Once the application is installed, you will be able to run the application. Note that this 
does not happen automatically; rather, you need to locate and launch the app as you 
wouid any other Android application. Figuře 9-6 shows an example of the sample 
application successfully installed. 
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Figuře 9-6. If the build process has gone to pian, the sample application will be shown in the application menu. 




NOTE: With the release of the Android 2.3 SDK (Gingerbread) in early December 2010, a bug was 
introduced that prevents PhoneGap applications executing for this version of Android (previous 
versions are unaffected). At the time of writing, this bug is being monitored in the Android issue 
tracker at the following URL: 

http ://code. google. cotn/p/android/issues/detail?id=12987- 

If you are looking to build and release an Android web application that ships natively using 
PhoneGap, then this is a very important issue to keep track of. Unfortunately, there is no way of 
working around this particular bug if deploying your web app with a native wrapper is a priority 
for you, SO we wouid recommend starring the issue in the issue tracker if it is not resolved by the 
time you read this chapter. 

Leťs now have a look at the application. Figuře 9-7 shows a screen capture of the 
sample PhoneGap application. 
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Figuře 9-7. The PhoneGap sample application is running. I wonder what those buttons do? 



With the application now running, we will dive in and have a look at some of the code 
behind the sample. This will give you an understanding of the kinds of things that you 
can do using PhoneGap that aren't possible in a standalone web application. 
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NOTE: Investigating and working with the PhoneGap sample application is best done if you 
actually have an Android device. This is because tlie sample works with device-level features (as 
you wouid expect) and the behavior of these is pretty limited in the emulátor. 

You will still be able to look at the code using the emulátor, and we will look at alternativě ways 
to monitor the device-level communication, but nothing beats holding your Android phone and 
having device-level features working from a web application. 



Investigating tlie Sample Application 

While dissecting the entire sample is probably overkill, iťs worth having a look at the 
way PhoneGap does a few things. First, we will have a look at how PhoneGap 
communicates with the device's accelerometer. 



Accelerometer Data Capture 

As discussed in Ghapter 1 , PhoneGap provides support for bridging to a number of the 
device sensors. The accelerometer is one of the more interesting sensors, as it can be 
used to create some fairiy novel interactions for games and other Interactive 
applications. 

The code generated in the PhoneGap sample application for monitoring the 
accelerometer is shown here: 

var accelerationWatch = falše; 

var toggleAccel = function() { 
if (accelerationWatch) { 

navigátor . accelerometer . clearWatch (accelerationWatch) ; 
updateAcceleration( { 
X : "", 

y : ""' 
z : " " 

}); 

accelerationWatch = falše; 
} else { 

accelerationWatch = true; 
var options = new Object(); 
options.frequency = 1000; 

accelerationWatch = navigátor. accelerometer. watchAcceleration( 
updateAcceleration, function(ex) { 

navigátor . accelerometer . clearWatch (accel_watch_id) ; 

alert("accel fail (" + ex.name + ": " + ex.message + ")"); 
}, options); 

} 

}; 

function updateAcceleration(a) { 

document .getElementById( 'x' ) . innerHTML = roundNumber(a.x); 




document.getElementById('y').innerHTML = roundNumber(a.y); 
document .getElementById( ' z ' ) . innerHTML = roundl\lumber(a.z); 

} 

The preceding code defines a function called toggleAccel, which is called in the onclick 
event of the Toggie Accelerometer button (shown in Figuře 9-7). As you can see, the 
code is reasonably trivial, and data is retrieved from the acceleronneter by the JavaScript 
code making a call to the accelerometer. watchAcceleration method, which has been 
attached to the globál navigátor object. 

The method takés three parameters: 

■ The first paranneter is for a success callback; it is called when an 
accelerometer reading has been obtained from the device. When 
executed, the callback function is passed a single object parameter 
that has values in the x, y, and z attributes. In the sample application, 
these values are simply updated on the display via the 
updateAcceleration function. 

■ The second parameter is for a failure callback, and this is triggered if 
PhoneGap receives an error while attempting to obtain accelerometer 
data. 

■ The third and finál parameter specifies options that can be used to 
influence the retrieval of the accelerometer data. In the sample 
application, we can see that the frequency of reporting data is set to 
1000 milliseconds through the frequency option. 

We can also see that, if we call the toggleAccel function a second time (when the 
accelerometer is being monitored), monitoring the accelerometer is cancelled via the 
accelerometer. clearWatch function. 

Camera and Photo Library 

Another useful bridging feature of PhoneGap is the ability to grab a photo from the 
device. Rhotos can be imported into the application either from the camera directly or 
from the user's photo library on the device. The code snippet in the PhoneGap sample is 
shown here: 

function show_pic() { 
var viewport = document. getElementById('viewport'); 
viewport. style. display = ""; 

navigátor. camera. getPicture(dump_pic, fail, { quality: 50 }); 

} 

function dump_pic(data) { 
var viewport = document. getElementById('viewport'); 
console.log(data); 
viewport. style. display = ""; 
viewport. style. position = "absolute"; 
viewport. style. top = "lOpx"; 
viewport. style. left = "lOpx"; 

document. getElementById("test_img") .src = "data:image/jpeg;base54," + data; 




} 

function fail(fail) { 
alert(fail); 

} 

The show_pic function in tlie preceding code is called when the Get Picture button 
(sliown in Figuře 9-8) in the sample interface is clicl<;ed. To view this button in the 
emulátor or standard DPI device, you will need to scroll down the page. 
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Figuře 9-8. Scroll down the sample interface to reveal the extra demo buttons. 

Using PhoneGap to retrieve a picture involves calling the camera.getPicture method, 
which is once again attached to the navigátor object. As you can probably see, 
getPicture uses a method signatuře similar to watchAcceleration, which is used to 
monitor the accelerometer: 

■ The first parameter takés a success callback, and this will be called in 
the case that an image is back from the device. 

■ The second parameter takés a failure callback, which is called when 
no image is returned. This includes the situation where the user 
cancels taking the picture. 

■ The third and finál parameter takés options that affect the behavior of 
the getPicture method. There are three different named options that 
can be specified for the options object: 
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■ quality (default: SO): A numeric value in the range of 1 to 100 
that specifies the quality of tlie image tínat sliouid be returned. 
Wliile you may be tliinking that you shouid just set the image 
quality to 100 so you get the very best image, images with 
quality values above 90 or so can get large very quickly. It is 
recommended that the default setting be used. 

■ destinationType (default: DATA_URLj: An enumerated value for 
how the image data shouid be returned. The two valid JavaScript 
values that can be specified for this option are 

Camera . DestinationType . DATA_URL and 

Camera. DestinationType. FILE_URI. (A comparison between data 
URLs and file URIs [uniform resource identifiers] can be found in 
the following note.) 

■ sourceType (default: CAMERAJ: For Android, this can be specified 
as one of two values. One is Camera. Picturesourcetype. CAMERA, 
which specifies retrieving a new image from the camera, and the 
other is Camera. PictureSourceType.PHOTOLIBRARY, which 
specifies retrieving an image from the photo library on the 
device. 

With that in mind, if we wanted to retrieve an image from our Android device's photo 
library rather than the camera, and then wanted to return the file URI for the selected 
image, the following code wouid do the triek: 

navigátor. camera. getPicture(successHandler, failureHandler, { 
quality: 50 j 

destinationType: Camera. DestinationType. FILE_URIj 
sourceType : Camera . PictureSourceType . PHOTOLIBRARY 

}); 

The result of calling the preceding code wouId yield a display similar to that shown in 
Figuře 9-9. 



Figuře 9-9. PhoneGap can be used to retrieve photos from the photo library as weil as the camera. 



NOTE: Previously, we made reference to the use of data and tile URIs. Typically, images in HTML 
are loaded from either a file or an HTTP URI string — for example, ■ 
f ile : //resources/test . j pg and http : //test . com/test . j pg are examples of a file I 
and an HTTP URI, respectively. While these are the most common ways to load an image (or I 
other resources) into an HTIVIL document, they are not the oniy way to do so. I 

Data URIs offer an alternativě to referencing an external resource, and are able to encapsulate I 
the actual data that shouid be displayed. Data URIs can be particularly useful when developing ■ 
mobile web apps, as resource data can be included within HTIVIL or CSS, or even copied to local 
storage for caching purposes. This in turn reduces the number of remote requests that need to 
be made to display a page, which can go a long way toward speeding up a mobile web ^1 
application. 

For more Information on the data URI formát, the Mozilla Developer Center offers a nice 
explanation (see https://developer.mozilla.org/en/The_data_URL_scheme). 



Notification Events 



The last example from the PhoneGap sample project that we will work through involves 
how it exposes functions that allow you to make the phone beep or vibrate. Iťs 
reasonably trivial, and the code to make it work is and nice and simple too. Leťs take a 
look: 

var beep = function(){ 

navigátor . notification . beep(2) ; 

} 

var vibrate = function(){ 

navigátor. notification. vibrate (o); 

} 

Hooray for simplicity! In the preceding code, PhoneGap attaches a notification object 
to the globál navigátor object, and this provides a number of methods. The two that we 
are accessing here are beep and vibrate. 

The beep method takés a single parameter that specifies the number of times that we 
wouid like the phone to beep. The vibrate method also takés a single parameter; 
however, in this instance we are specifying the length of time (in milliseconds) that we 
wouId like to phone to vibrate for. While this example is quite trivial, we shouid not 
discount the usefulness of being able to perform these kinds of operations using the 
device. When coupled with the ability to track a user's position and run applications in 
the background, there are some pretty useful things that we can implement in our 
applications— especially if we happen to be writing a geosocial game. We will start to 
look at our game in the next chapter. 

A Simple PhoneGap Mapping App 

In the last chapter, we worked through a number of examples involving mapping. Leťs 
now look at how we take our finál sample from the chapter and embed that in a 
PhoneGap native wrapper. 

As we aiready have a sample project that has been configured to build correctly, leťs 
copy that directory and create a new project called MapTest. 

Tweaking the Sample PhoneGap Project 

While the sample project does provide us all the basic building blocks that we need to 
build our application, there are some things we need to do if we want to actually build a 
production application on it. 

Ideally, this wouId involve all references to "Sample" being replaced with something more 
meaningful. This is actually a little trickier than you might expect, but, if you have worked 
with native Android applications in the past, you shouid be comfortable with the process. 
If you haven't, don't worry— we'll walk you through what is required step by step. 
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First, we need to change the name of the native executable that is created during the 
build process. This is done using the android command-line tools— iťs similar to what 
we did earlier when generating our local.properties file. Run the foliowing command 
from the maptest directory: 

android update project -n maptest -p ./ 

Runnlng this command shouid produce output similar to that displayed in Figuře 9-10. 



bosh 



bash 



O emufatar 



damomacinaptest danio$ android updatB project 
Updated Iccal. properties 
File build. Kml is too old and need5 to be updated 
Updated tile . /build. Ximl 
ilainairiac:naptest dainiQ$ [j 



■p ■/ 
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Figuře 9-10. Renaming the sample project to "maptest" is done using the android command-line tool. 



This will update build. xml, and means that our application will now be built as maptest- 
debug.apk instead of sample-debug.apk when built in debug mode (ant debug). AI! other 
references to "Sannple" remain intact, though, so we need to continue on our mission. 

Next up is updating the application title to "MapTest." Making this change means that 
our application will be shown on the device with the title of "MapTest" in the application 
menu, rather than "Sample." 

To makethis change, locate the strings.xml file in the res/values directory in your 
MapTest project, and then modify the reference of "Sample" to "MapTest." 

The foliowing is what the file shouid look like after you have made your changes, with 
the bold text highiighting the change: 




<?xml version="l.O" encoding="utf-8"?> 
<resources> 



<string name="app_name">MapTest</string> 
<string name="go">Snap</string> 
</resources> 

At this point, you shouid be able to build and install the application to the emulátor and 
have it show up as "MapTest" rather than "Sample." So leťs try that now. As we did 
earlier when we were working with the sample application, we'll use Ant to build and 
install the application to the emulátor or device: 

ant debug install 

If you have completed the previous steps successfully, you shouid be able to see a 
MapTest application now installed in the emulátor. An example screen capture is shown 
in Figuře 9-11. 
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Figuře 9-1 1 . After making some simple updates, our MapTest application is visible in the emulátor — but we 
aren't finished yet. 



Tidying Up: Renaming Classes 

We couid now quite happily carry on and embed our mapping application into the 
PhoneGap application without making further changes. Given that we are going to be 
building applications that we want to deploy to the Android marketplace, iťs probably 
worth looking at what is needed to remove additional references to "Sample" from the 
PhoneGap sample project. 
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There aren't too many places we have to do this, but iťs worth pointing out that this is a 
little more complicated than what we did in our previous steps. So, if you wouid prefer to 
tackle this once you are actually building a production application instead, you are quite 
weicome to do so. 

First, we need to change tine class com.plionegap.Sample.Sample to sometining that 
makes sense for our application. Depending on the tools you are using, this process can 
be as simple as pressing a Refactor button and letting the IDE work it out. However, as 
we are building web apps and our primary tool is a text editor, we will need to make the 
change in a few more places. So leťs begin: 

1. Update the com/phonegap/Sample directory structure to match something more in 
line with what we are building. Something like com/prowebapps/maptest is a good 
choice. 

2. Next, rename the sample. java file MapTest. java, as this better represents the 
application we are building. 

3. Finally, you will need to update the contents of the Java file, and change the 
com.phonegap. sample and sample references to com.prowebapps.maptest and 
MapTest, respectively. 

The following is a sample of what the MapTest. java file might look like after you have 
completed the necessary changes: 

package com.prowebapps.maptest; 

import android.app.Activity; 
import android.os.Bundlej 
import com.phonegap.*; 

public class MapTest extends DroidGap 
{ 

@Override 

public void onCreate(Bundle savedInstanceState) 
{ 

super .onCreate( savedInstanceState); 

super . loadUrl( "f ile : ///android_asset/www/index . html" ) ; 

} 

} 

Once the Java source file has been modified, we are halfway there. Now we just need to 
update the AndroidManifest.xml file in the project root directory to reflect the changes 
we have made. Once again, this involves modifying the com.phonegap. Sample reference 
to com.prowebapps.maptest and the Sample reference to MapTest. 

The following is an example of what the AndroidManifest.xml file wouId look like after 
the changes. Once again, the modified sections are marked in bold. 

<?xml version="l.O" encoding="utf-8"?> 

<manifest xmlns :android=" http://schemas.android.com/apk/res/android" 

package= "com.prowebapps.maptest" android:versionName="l.l" 
android: versionCode="l"> 
<supports-screens 
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android 
android 
android 
android 
android 
/> 

<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 
<uses-permi 



:largeScreens="true" 
:normalScreens="true" 
: smallScreens="true" 
:resizeable="true" 
:anyDensity="true" 



ssion 
ssion 
ssion 
ssion 
ssion 
ssion 
ssion 
ssion 
ssion 
ssion 
ssion 
ssion 
ssion 
ssion 



android ; 
android ; 
android ; 
android ; 
android; 
android; 
android; 
android; 
android; 
android; 
android ; 
android ; 
android ; 
android; 



name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 



android, 
android, 
android, 
android, 
android, 
android, 
android, 
android, 
android, 
android, 
android, 
android, 
android, 
android. 



permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 



.CAMERA" /> 
.VIBRATE" /> 

,ACCESS_COARSE_LOCATION" /> 
,ACCESS_FINE_LOCATION" /> 
, ACCESS_LOCATION_EXTRA_COMMANDS " /> 
.READPHONESTATE" /> 
.INTERNET" /> 
,RECEIVE_SMS" /> 
,RECORD_AUDIO" /> 
.MODIFYAUDIOSETTINGS" /> 
.READCONTACTS" /> 
,WRITE_CONTACTS" /> 
,WRITE_EXTERNAL_STORAGE" /> 
.ACCESS NETWORK STATE" /> 



opplication android : icon="@drawable/icon" android : label="|5)string/app_name" 
android : debuggable="true" > 
<activity android :name=" .MapTest" 

android: label="(5istring/app_name" 
android : conf igChanges="orientation | keyboardHidden"> 
<intent-f ilter> 

<action android:name="android.intent.action.MAIN" /> 
<category android:name="android.intent.category.LAUNCHER" /> 
</intent-f ilter> 
</activity> 
</application> 

<uses-sdk android:minSdkVersion="2" /> 
</manifest> 



That shouid do it. To make sure you haven't made any typos, rebuild the application and 
attempt to run it in tine emulátor. If you made an error somewlnere along tine way, tinen a 
screen like Figuře 9-12 will be displayed. 
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Figuře 9-12. Typos can occur while renaming classes in the sample proJect, resulting in application craslies. 

If you do see an error while trying to load your application, then double-check that the 
activity name in the AndroidManifest.xml file matches the name you gave to the main 
application class, bearing in mind case-sensitivity. 

This brings us to the point where things are structured correctly for building our test 
mapping application. When deploying a production application, there are still a few 
additional things to cover (such as updating the application icon to something other than 
the default), but we will cover those in Chapter 1 1 . 

For now, leťs continue to focus on getting some existing HTML code into our PhoneGap 
wrapper. 

Transferring Existing Code into a PlioneGap App 

In the last chapter, we put a fair bit of effort into our boilerpiate mapping application, so 
we will use those files in the new MapTest project as weil. 

We will work through the process of embedding the application step by step here: 

1. Copy the mapapp.html, mapapp.css, and mapapp. js files from the snippets 
directory into the assets/www folder of our new MapTest project. 

2. Copy the entire img directory that accompanies the mapapp . html file to the 
assets/www folder also. This will result in the four images being stored in the 
assets/www/img directory. 
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3. Copy ]query-l.4.2.min. js from the shared js library of our sample code into the 
assets/www folder also. 

4. Delete the existing index.html and master. css files from the assets/www folder, 
but leave phonegap. js, as it will be required to enable the bridging calls. 

5. Rename the mapapp.html file to index.html so it becomes the file that is opened 
with the native application is launched. At this point, the folder structure of the 
assets/www folder shouid look like Figuře 9-1 3. If your folder structure matches, 
then continue on and make the modifications to the index.html file to reference 
the updated file locations. These are outlined in the finál two steps. 



NOTE: While we have been very good at referencing and reusing libraries such as jQuery from a 
centrál location for the examples in the book so far, once we start working with a PhoneGap 
project, we aren't able to do that anymore. 

We will instead have to copy these shared resources into the assets/www folder; otherwise, 
they will not be transferred as part of the native bundle. When working with larger projects, we 
wouid additionally recommend implementing some kind of build scriptto handle transferring the 
required resources into your bridge application. This will make it simpler to work on a centrál 
code base that is able to be deployed directly to the Web and also through native wrappers like 
PhoneGap. 

For more Information on build tools, we recommend looking at Apache Ant 
(http://ant.apache.org) given theAndroid platform is Java based; however, if you are 
looking for build alternatives, then Rake (www.rubyrake.org) is also worth a look. 
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Figuře 9-1 3. ffle structure of the assets/www folder in the MapTest PhoneGap projed 



6. Make some tweaks to the new index. html and mapapp. js files so that they 
reference the files stored within the assets/www folder and nothing above that. The 
oniy modification that is required is changing the path of the jQuery library to 
reference the one stored in the assets/www folder instead of the shared location 
we have been using. 

7. Include phonegap.js in the main HTML file so we can use the bridging functions 
provided by PhoneGap. 

The modifications to the updated index.html file (previously mapapp.html) are shown 
here: 

<!DOCTYPE html> 

<html> 

<head> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 
<link rel="stylesheet" media="screen" href="mapapp.css" /> 
<script type="text/javascript" src=" jquery-l.4.2.min. js"></script> 
<script type="text/javascript" src="mapapp. js"></script> 
<script type="text/javascript" src="phonegap. js"></script> 

<script type="text/javascript" src="http: //maps. google. com/maps/api/js?sensor=false"> 
</script> 

<script type="text/javascript"> 
function initializeQ { 




var latlng = new google. maps.LatLng(-33. 866, 151.209); 



MAPAPP.init(latlng, 13); 

MAPAPP.addMarker(latlng, 'Sydney', ' Sydney Australia ' ); 
MAPAPP.addMarker(new google. maps. LatLng(-33. 859, 151.209), 'The Rocks'); 
MAPAPP.addMarker(new google. maps. LatLng(-33. 857, 151.215), 'Sydney Opera House'); 
MAPAPP.addMarker(new google. maps. LatLng(-33. 861, 151.211), 'Circular Ouay'); 

// update the map display 

MAPAPP . updateDisplay O ; 
} // initialize 
</script> 
</head> 

<body onload="initialize()"> 

<hl class="simple f loating">Mapping App Boilerplate</hl> 
<div id="map_canvas" style="width:lOO%; height:lOO%"></div> 
<div id="marker-nav"> 

<img src="img/navigation-arrow.png" class="left disabled" /> 

<span class='marker-title'>Test Text</span> 

<img src="img/navigation-arrow.png" class="right" /> 
</div> 

<div id="marker-detail" class="child-screen"> 

<div class='contenť>Some Test Content</div> 

<button class= ' close ' >Close</button> 
</div> 
</body> 
</html> 

As you can see, aithough we went through a number of steps to copy the files across, 
oniy very simple changes are required to the HTML. Our web application is now all 
wrapped up in PhoneGap and can be deployed as a native application. This is done by 
once again building the application (using Ant) to redeploy the application to the 
emulátor. 

A screen capture from the emulátor running our native MapTest application is shown in 
Figuře 9-14. 
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Figuře 9-14. Our boilerpiate mapping application wrapped up as a PhoneGap native application 



If you get a different result and the map does not display as expected, then try running 
the following command and look for possible JavaScript errors: 

adb logcat 

For instance, Figuře 9-15 sinows some example output wfien the jQuery JavaScript 
included in the index.html file isn't updated correctly. 
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Figuře 9-1 5. For locating JavaScript errors, adb logcat is invaluable. 



As mentioned earlier, Appendix A contains more information on debugging Android web 
apps (and JavaScript) in generál, so, if things aren't going to pian, iťs weil worth a look. 



Summary 

in this chapter, we looked at PhoneGap and explored the capabilities it offers. 
Additionally, we walked you through the changes that need to be made to correctly 
structure the sample application provided with a PhoneGap release for distribution at a 
later stage. 

Finally, we took the boilerpiate mapping application that we built in the previous chapter 
and examined what was required to package that code in a PhoneGap wrapper. 

In the next chapter, we will start putting together the building blocks that we have 
worked through in the previous two chapters, and actually get into putting some code 
together for our geosocial game, Moundz. 




Integrating with Sociál 
APls 

Now that we've put many of the foundations in pláce, we can start putting together our 
geosocial game application. In this chapter, we'll build a game called Moundz. Moundz 
Is a geosocial game that piggybacks off existing geosocial networks such as Foursquare 
and Gowalla. The generál concept is that geosocial check-ins of people around the 
worid become resources. These resources are then collected and redeployed in a quest 
for Virtual worId domination. In Moundz, players help to build ant mounds that become 
their strongholds, from which they can launch an assault on enemy territory. Oniy the 
strong and diligent will survive. 

Interested? WeII, leťs get started. 

Connecting to Web APls 

One of the best things you can do as an application developer is consider what other 
existing web applications you can hook into to service some of the needs of your app. 
This will not onIy save a significant amount of development required to build your 
application, but will likely provide you access to an established group of users that are 

actively using another application. 

For instance, in Moundz we are going to need some kind of geographically located 
resources that people playing the game can "mine" to build their "bases." Rather than 
building our own database of locations, we are much better served by tapping into an 
existing application that provides that kind of data aiready. 

As it turns out, geosocial networks like Gowalla and Foursquare have exactly the kind of 
information we need, and they both provide an API that exposes their data. Like most 
things in life, though, iťs not quite that easy. The majority of APls that have been built 
usually offer integration via XML and sometimes JSON, but, when you are building an 
application that is going to be "mashed up" at the client, you often need something 
called JSONP support. The next section gives an overview as to why. 
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Essentially, JSONP is a workaround to a problém we will look at throughout this section. 
It involves a clever technique that web developers started using to get around what is 
known as tlie same-origin policy (http://en.wikipedia.org/wilci/Same_origin_policy), 
which is enforced in web browsers. Witin the same-origin policy in pláce, JavaScript 
code running in a browser is prevented from making an XMLHttpRequest 
(http://en.wikipedia.org/wiki/XMLHttpRequest) to a URL that is different from the 
domain the script is running from. Therefore, if you attempt to access an application's 
API from a client-side script running on a separate domain, the browser will step in and 
prevent it from happening. 

To illustrate the problém, we will work through a small example. For example, consider 
the following code, which accessesthe public Twitter API (see http://dev.twitter.com 
for more Information) and displays the tweets on the page. 

<html> 

<script src=". ./. ./js/jquery-l.4.2.min. js"></script> 
<script> 

function showData(data) { 
var tweetitems = ' ' ; 

if (! data) { 

tweetitems = ' <li><strong>Could not retrieve tweets. </strong></li> ' ; 

} 

else { 

for (var ii = 0; ii < data.length; ii++) { 

tweetitems += '<li>' + data[ii].text + '</li>'; 
} // for 

} 

$('#tweets' ) .html(tweetltems); 
} // showData 

$(docu[nent) .ready(function() { 

// make the request to the geonames server 
$.ajax({ 

url: ' http://api.twitter.eom/l/statuses/public_timeline. json' , 
dataType: 'json', 
success: showData 

}); 

}); 

</script> 
<body> 

<ul id="tweets"> 

</ul> 
</body> 
</html> 

The sample itself is simple enough— we make a request to the endpoint for the Twitter 
public timeline and then parse the response, filling the #tweets element with the tweets 
retrieved. 



Leťs run that now. So that you can easily look at whaťs going on in the background, we 
recommend working through this sample in your desktop browser. (We will be using 
Clirome.) Figuře 1 0-1 shows the output generated from attempting to access the Twitter 
API using JSON from our local web server. 



1 3l0.1.1.3:80BOÍsmpI>Ms/10, X '\ p7V 
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• Could not retrieve tweets. 



Figuře 1 0-1 . Attempting to access the Twitter JSON API from our local web server yields no results. 



Unfortunately, Figuře 10-1 really doesn't give us much idea as to what is going on — 
except for the fact that our error-handling code is working correctly. So iťs time to dig in 
a little. For this sample, we will be using the WebKit Inspector (see Appendix A for more 
details on debugging tools) to have a look behind the scenes. If you are using Chromé, 
try looking in the View > Developer menu for the developer tools. Other browsers offer 
similar tools, so feel free to use your preferred toolset here. 

Figuře 10-2 shows the network view from the Chromé developer tools. 
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Figuře 10-2. The network view ofthe Chromé developer tools shows us where the problém exists. 

The network view in tlie developer tools confirms that the browser has indeed blocked 
the cross-domain request in accordance with the same-origin policy. 

This is where a JSONP workaround comes into play. JSONP works within the bounds of 
the sanne-origin policy, using rules that permit script includes fronn other domains. So, 
whereas a standard JSON request occurs via the XMLHttpRequest mechanism, a 
JSONP request is inserted and run as a script tag. This nnay sound a little confusing 
and take some time to get your head around if you haven't come across JSONP before. 

WeII, leťs update our Twitter sample to use JSONP and see if we can gain an 
understanding of whaťs going on. 

<html> 

<script src=" . ./. ./js/jquery-l.4.2.min. js"></script> 
<script> 

function showData(data) { 
var tweetitems = ' ' ; 

if (! data) { 

tweetitems = ' <li><strong>Count not retrieve tweets.</strong></li>' ; 

} 

else { 

for (var ii = 0; ii < data.length; ii++) { 

tweetitems += '<li>' + data[ii] .text + '</li>'; 
} // for 



} 



$ ( ' #tweets ' ) . html (tweetitems ) ; 
} // showData 

$(docu[nent) .ready(function() { 

// make the request to the geonames server 
$.ajax({ 

url: ' http://api.twitter.eom/l/statuses/public_timeline.json ' , 
dataType: 'jsonp', 
success: showData 

}); 

}); 

</script> 
<body> 

<ul id="tweets"> 

</ul> 
</body> 
</html> 

The preceding code shows the modification required to have our test application 
communicate via JSONP rather than JSON. You can see here that jQuery does an 
excellent job of abstracting the complexity of JSONP away from us behind its $.ajax 
function. Figuře 10-3 shows an example of the output generated by the modified sam 
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Figuře 1 0-3. Using JSONP, we can now retrieve the tweets of the worid via the Twitter public timeiine. 



Now that we have looked at how simple it is to have jQuery issue a JSONP request for 
US, leťs take a quick look at what is going on behind the scenes. To achieve this, we will 
make a copy of our twitter-test.html file and replace the previous showData function 
with the following code: 

function showData(data) { 
var tweetitems = ' ' ; 

for (var ii = 0; ii < document.scripts.length; ii++) { 
var script = document.scripts[ii]; 

if (script. src) { 

tweetitems += '<li>' + script. src + '</li>'; 
} // if 
} // for 

$ ( ' #tweets ' ) . html (tweetitems ) ; 
} // showData 

So, rather than outputting the text of the tweets to the HTML, we are now writing out the 
source file location of any scripts that are currently included in the page. Figuře 10-4 
shows an example of what is displayed. 
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Figuře 1 0-4. Scripts that have been included in an HTML page reveal something of the nature of JSONP. 



Ah, there we go— our call to Twitter has been included as a separate script in our page, 
but this doesn't explain how we get the data back into our application. For that, we need 
to dig a little further. Figuře 10-5 shows an example of the output that Twitter is 
generating when we call the script shown on this page. 
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Figuře 1 0-5. Example output of the Twitter API when called using JSONP 

Things are starting to make sense now— the included script passes data back through a 
function call. However, tliis is not a function that we have defined, but rather a function 
that has been created by jQuery with the specific purpose of receiving the data from the 
JSONP call. Once the jQuery function has received the data, it simply passes that 
Information along to the callback that we provided when we made our $.ajax call. 



NOTE: In generál, you are probably better off usIng a JavaScript llbrary such as jQuery to handle 
your JSONP calis, glven the steps that are Involved in getting It working. While we have covered 
some of what goes on behind the scenes here, It is far from an exhaustive list of the work that 
needs to be done. For further Information, the followlng blog post provides a lightweight script 
that shows how JSONP works, and also provides an alternativě to some of the more heavyweight 
implementatlons In jQuery and the llke: 

www.nonobtrusive.com/2010/05/20/lightweight-jsonp-without-any-3rd-party- 
libraries. 




Dealing with APls That Lack JSONP Support 

In the instances where an API does not provide JSONP access, what are the options? 
This is a pretty important question in our case, as at the time of writing neither Gowalla 
nor Foursquare supports JSONP-style calis in its API. 

We will briefly look at three different options that will provide us access to web services 
that do not provide JSONP-style access. 

Writing a Server-Side Proxy 

Before JSONP became a popular option for writing client-side "mashups," developers 
wouid traditionally write their own set of web services that wouid proxy the remote 
services. These web services wouid be deployed to the same domain that wouid serve 
the application, and this wouid mean no calIs violated the same-origin policy. The 
implementation of such a solution will vary depending on the language you are working 
with, and the implementation details are beyond the scope of this book, but there is a lot 
of good Information out there if this is something that you require. 

Another alternativě to writing your own server-side proxy, given that JSONP is now 
available to you, is to use a third-party service to wrap web services that provide oniy a 
JSON implementation with JSONP. A couple of good examples of this are the following: 

■ http://jsonpify.heroku.com 

■ http://jsonproxy.appspot.com 

Both services have source code available and are hosted in cloud-hosting services, so 
you can modify them to suit your own specific requirements. 



Yahoo Query Language 

Yahoo Query Language (YQL) is fantastic; there really aren't enough nice things that can 
be said about it. It is essentially a very robust and generic proxy that can be used to 
request data from varying sources and return it in a standardized XML or JSON (with 
JSONP support) formát. 

Interacting with VOL is done through the use of an SOL-like syntax, which is where the 
OL part of the name comes from. Figuře 1 0-6 shows a screenshot of the developer 
console, which is one of the core tools of the VOL suitě. The console can be found at 
http://developer.yahoo.com/yql/console. 
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Figuře 1 0-6. The developer console is a great pláce to begin to understand the possibilities of YQL 



One of the really nice things about YQL is its use of data tables. These data tables 
provide YQL Information on how to interact and obtain Information from various services 
around the Web. When you first load the YQL console, you will probably see around 160 
data tables initially available, and these relate mostly to tables that interface with other 
Yahoo! services. By accessing the community tables (which you can do by selecting the 
Show Community Tables link on the right), you galn access to almost 1 ,000 different 
tables that you can interact with, and both Foursquare and Gowalla tables are included 
in this set. 

In Foursquare's oase, the following is a YQL query that is designed to interact with its 
venues API endpoint: 

select * 

from foursquare. venues 
where geolat="33. 7772869" 
and geolong="-84. 3975068" 

In addition to running requests through the console, you can execute YQL through a set 
of published web services. In each oase, a REST query for the information is displayed 
at the bottom of the console interface. This REST query can then be copied and pasted 
into your own client-side JavaScript— for instance, directly into a jQuery a jax function 
call. We won't include a sample URL here, as these are fairiy unreadable, since they 
contain the escaped SQL statement as part of the query. It is fairiy simple to recognize 




an application using YQL though (using the developer tools of course), as it will be 
routing requests through http://query.yahooapis.com/vl/public/. 

While it wouid be great to go into more depth on YQL, we won't be using it to solve our 
current issue for accessing Foursquare or Gowalla (tine reasons for this will be outlined 
very soon), so that wouId be counterproductive. However, it is definitely worth a look 
when you have the time, as it can definitely be extremely useful. 

PhoneGap Native App 

As strange as it may seem, using PhoneGap as a native wrapper actually provides you 
some additional advantages beyond what we have been taiking about so far. PhoneGap 
accesses the HTML, GSS, and JS files for the mobile application using the file URI 
scheme (http://en.wikipedia.org/wiki/File_URI_scheme) ratherthan HTTP (or 
HTTPS). In doing this, PhoneGap actually circumvents most of the security restrictions 
that are placed on web applications and pages that are loaded from a web server. 

This is more of a side effect than a design feature, and it is not something that will be 
available in all bridging frameworks. As such, it is recommended that you oniy use this 
workaround when you are sure that you will be deploying your mobile web application 
onIy via PhoneGap. 



Introducing the Geominer API 

In the previous section, we looked at a number of different strategies for dealing with an 
API that doesn't support JSONP requests. We now have to decide which one we want 
to use. Before we do that, leťs consider our available tools and design goals for the 
project: 

■ While the YQL solution is elegant, the preferred geosocial API is 
Gowalla (given some excellent API features), and the current YQL 
community datatables (www.datatables.org) for Gowalla don't support 
all of the Gowalla API features. 

■ In Moundz, we will be using Twitter for authenticating users rather than 
writing our own login systém. We will go into this process in more 
detail soon, but for now leťs just say that, at the time of writing, 
Twitter does a better job of offering mobile-friendly experiences 
through its more established APls. While it recently released a 
JavaScript toolset called Twitter Anywhere 
(http://dev.twitter.com/anywhere), login features are still very 
desktop oriented. 

■ Our primary focus in this book is building Android web apps, which 
means that, while using PhoneGap wouId be a suitable workaround, 
the deployment of the app as a standalone web application wouId not 
be an option. This is less than ideál. 



CHAPTER 10: Integrating with Sociál APls 



Based on these factors, it is probably best for us to implement our own server-side API 
that will handle the interaction with other application APls for us, and provide a single 
JSONP-enabled API that both our mobile web application and others couid deal with. 
Figuře 10-7 shows how this API provides some "middleware" for building our geosocial 
game. 



f 










"v 


Moundz Web Client 






JavaScript 




j 




All Requests 














Geominer API 






Groovy on Google App Engine (Gaelyk) 


J 


i 

logíns 
(via OAuth) 1 








i 

ResDurce 
Reqjests 






f 






\ 


Twitter 
API 






Gowalla API 




v J 










J 



Figuře 1 0-7. Tfte Moundz API aggregates our multiple external APls into a single interface. 

Given that the title of this book is not Building API Mashups with Google App Engine, we 
won't be going into great depth about the work required on the server side. We will 
instead be focusing on how to use the API to build our mobile application on the client 
side. 

Additionally, rather than build an API that is suited oniy to the needs of the Moundz 
sample application, we will build the Geominer API as generically as possible. This way, 
if you feel inspired to write an application similar to Moundz, you shouid be able to use 
the Information in these last few chapters of the book and the Geominer API to create 
your own masterpiece. 

For more information on the Geominer API and an inside look at the source code 
showing how it was built, check out the source code on GitHub, at 
http://github.com/sidelab/geominer. 



WeII, thaťs enough taik— leťs write some code. 




Locating Resources in Moundz 

The first step to worid domination in Moundz is collecting resources with which to start 
to build your ant mound. Your mound is essentially your base, which you will build over 
time, and you will need to mine resources from locations around your area and bring 
them back to your base. This is where the geosocial network data comes in — it supplies 
the base data that the Geominer API uses to feed the game data. 

Essentially, the process is as follows: 

1. Moundz requests resource data for resources near the current position from the 
Geominer API. 

2. Geominer passes the request to the Gowalla API and receives a list of Gowalla 
"spots" back for the specified position. This includes the total number of check- 
ins that have been made for each spot. If you are interested, have a look at the 
Gowalla API Explorer (http://gowalla.com/api/explorer)— we are using the list 
method of the spots endpoint. 

3. Geominer then returns a subset of the Information received from Gowalla, with a 
value for resources available. This value is equal to the total number of check-ins 
for the spot, less any resources aiready mined from that location since the game 
started. 

4. Moundz displays the Information received. 

With that in mind, leťs start putting the skeleton of the Moundz application together and 
implement a Nearby Resources screen. We will base the generál structure for the 
Moundz application on our mapping application boilerpiate, so leťs create a new 
directory for Moundz and copy the boilerpiate files there. 

The simplest pláce to take a copy of the files from will be the directory that we were 
working in when implementing our PhoneGap wrapper in the previous chapter. So, copy 
the files from /bridges/maptest/assets/www to /moundz. Once you have done this, you 
shouid have a directory structure that looks similar to Figuře 1 0-8. 
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Figuře 1 0-8. We will use our work from Chapter 9 for the starting point of the Moundz app. 



Then just a few tidy-ups are required before we can get into coding our game. First, 
rename mapapp.js and mapapp.css to moundz. js and moundz. css, respectively. 

Next, change the name of the MAPAPP module to MOUNDZ, as shown in the following code 
sample: 

MOUNDZ = (functionO { 
var module = { 

}; 

return module; 

})(); 

And finally, make the following updates to the index.html file: 

■ Remové (or comment out) the script include for phonegap. js, but leave 
the actual script there, as we will use it later when we bundle Moundz 
as a native app for marketplace distribution. 

■ Replace references to mapapp.js and mapapp.css with the Moundz 
equivalents. 

■ Replace references to I^APAPP with I^OUNDZ. 



Once those changes have been completed, your index.html file shouid appear similar to 
the following sample. The lineš that have been modified are shown in bold. 

<!DOCTYPE html> 

<html> 

<head> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 

<link rel="stylesheet" media="screen" href="moundz.css" /> 

<script type="text/javascript" src=" jquery-l.4.2.niin. js"></script> 

<script type="text/javascript" src="moundz. js"></script> 

</-- <script type="text/javascript" src="phonegap.js"></script> --> 

<script type="text/javascript" src= " http : //maps. google. com/maps/api/js?sensor=false"> 

</script> 

<script type="text/javascript"> 
function initializeQ { 

var latlng = new google. maps. LatLng(-33.866j 151.209); 

MOUNDZ.init(latlng, 13); 
MOUNDZ . updateDisplay ( ) ; 

} // initialize 

</script> 

</head> 

<body onload="initialize()"> 

<hl class="simple floating">Moundz</hl> 

<div id="map_canvas" style="width:lOO%; height:lOO%"></div> 
<div id="marl<er-nav"> 

<img src="img/navigation-arrow.png" class="le-Ft disabled" /> 

<span class='marl<er-title'>Test Text</span> 

<mg src="img/navigation-arrow.png" class="right" /> 
</div> 

<div id="marl<er-detail" class="child-screen"> 

<div class='contenť>Some Test Content</div> 

<button class= ' close ' >Close</button> 
</div> 
</body> 
</htrtil> 

With the application template complete, we are ready to start putting the elements of 
our game together. 

Finding Nearby Resources with the Geominer API 

Again, the first step is gathering resources with which to build your base. As stated 
previously, resources are actually geosocial networl< check-ins that have been collected 
from either Foursquare or Gowalla (depending on the game). 

To find nearby resources, we will use the Geominer API resources search in combination 
with the Geolocation API that we looked at in Ghapter 6. The Geominer resources 
search follows the naming convention for all web services in the Geominer suitě. The 
following is the URL that we will be using for Moundz: 
http://api.geominer.net/vl/itioundz/resources. 



Each web service in Geominer follows the basic formát of 

http: / /api.geominei .net/api-version/appid/uebservice/method. The following list 
describes the details: 

■ api-version relates to the version of the Geominer API that we are 
using. We are using version 1 , so this becomes vl. 

■ appid refers to the application that is currently accessing the Geominer 
Services. The IVIoundz application has been configured to use the 
IVIoundz application ID, so this becomes moundz. 

■ webservice refers to the particular group of tools that we are using in 
the Geominer toolbox. In this oase, we are using the resources tools. 

■ method is used to indicate the particular operation that we are 
executing with the tools that we are using. This particular section of 
the call can be omitted if we want to access the default operation for 
the webservice. In the case of the resources tools, this is a search 
operation, which is what we wish to use, so this section can be 
omitted. 

We will now add some functionality to our MOUNDZ module to enable us to retrieve those 
resources through the Geominer API: 

MOUNDZ = (functionO { 

// initialize constants 
var DEFAULT_ZOOM = 8, 

GEOMINER_MOUNDZ_URL = 'http://api.geominer.net/vl/moundz'; 



function f indResources(callback) { 
// get the map center position 
var center = map.getCenter(); 

$.ajax({ 

url: CEOMINER_MOUNDZ_URL + '/resources', 
dataType: 'jsonp', 
data: { 

lat: center. lat(), 

Ing: center. IngO 

}, 

success: function(data) { 

processResourceSearch (data) ; 
if (callback) { 
callbackO; 
} // if 

} 

}); 

} // f indResources 



var module = { 



addMarker: addMarker, 
clearMarkers: clearMarkers, 



■FindResources: f indResources, 



return module; 

})(); 

The preceding code shows the modifications required. We are adding a f indResources 
function to our MOUNDZ module that will find resources based on the current map center 
position. The majority of this function is a jQuery Ajax call using JSONP, as we used 
earlier to access the Geonames data when first getting an understanding of JSONP. 
When we receive successful results from Geominer, these are passed to the 
processResourceSearch function. Leťs have a look at this function and its associated 
code now. 

function markResources(resourceType, deposits) { 
for (var ii = 0; ii < deposits. length; ii++) { 
// add the marker for the resource deposit 
addMarker( 

new google. maps. LatLng(deposits[ii] .lat, deposits[ii] .Ing), 
deposits[ii] .name, 

'<div class="resinfo"> ' + deposits[ii] .total + 
' resources at this location</div> ' ) j 

} // for 
} // markResources 

function processResourceSearch(data) { 
// clear any existing tnarkers 
clearMarkers O; 

// iterate through the resource types and pin 
for (var ii = 0; ii < data. resourceTypes. length; ii++) { 
var resType = data.resourceTypes[ii]; 

// mark the resources 

markResources (resType.typeName, resType. deposits); 
} // for 
} // processResourceSearch 

The two functions in this code are included in the MOUNDZ module as internal functions. 
As you saw in the f indResources function, processResourceSearch is called when we 
have received a successful response from the Geominer API. When this happens, 
existing mari^ers are first removed, and then new markers are added for each of the 
different resource types that have been retrieved from the API. 

In the case of Moundz, we have only one type of resource for the sake of simplicity, but 
we have implemented a for loop here to enable us to support additional resource types 
with relative ease if that is something that is desired at a later stage. 

For each of the resource types, the markResources function is called to display markers 
on the map as per the boilerpiate mapping application that we explored in Chapter 8. 



All we need to do now is to adjust the index.html file to make the call to the 
f indResources function of the MOUNDZ module when the page is loaded: 

<script type="text/javascript"> 
function initializeO { 

var latlng = new google. maps. LatLng(-33. 866, 151.209); 

MOUNDZ. init(latlng, 17); 
MOUNDZ. findResources(function() { 
MOUNDZ . updateDisplay O ; 



} // initialize 
</script> 

For the moment, we will leave out the location-detection part just to check that 
everything operates correctly. This leaves us having to make oniy a very simple change 
to our initialize function (shown in bold). Additionally, we increase the zoom level to 
17 from 13, which is more appropriate given the results we will get back from Geominer 
(courtesy of Gowalla in this initial oase). Figuře 1 0-9 shows an example of what we 
shouid see if everything has gone according to pian. 



Figuře 1 0-9. For Moundz, the Geominer API returns a list of Gowalla spots near the center of the map. 

As with our earlier work with the boilerpiate mapping application, the resource locations 
can be selected either by tapping a marker or by navigating using the left and right 
navigation arrows. Additionally, more detail for that location can be displayed by tapping 
the title of the location as before. At this stage, we have included some simple debug 
Information about the number of resources available. Figuře 10-10 shows the example 
debug Information that we have included for the moment. 
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Figuře 10-10. We will expand the resource information screen to include actions relating to the resource. 



Using Geolocation to Track Your Position 

Before we move on to including those extra features in the application, leťs make the 
modifications required to have the application use our current location instead of the 
static testing location that we have been using so far. Chapter 6 gave an introduction to 
the Geolocation API and the getCurrentPosition method. However, for Moundz it wouid 
be great if we couid track the user's location rather than just get the location in a single- 
shot request. 

This is actually very simple, and will involve replacing all of the code that we were using 
in the index.html initialize function with a run function in the moundz. js file as per the 
following code: 

I^IOUNDZ = (functionO { 

// initialize variables 
var map = null, 

posWatchld = 0; 



function run(zoomLevel) { 

// check that the watch hasn't already been set up 
// if it haSj then exitj as we don't want two watches... 
if (posWatchld !== O) { 
return; 



} // i-F 

// create the watch 

posWatchld = navigátor. geolocation.watchPosition( 

f unction(position) { 

var pos = new google. maps. LatLng( 
position . coords . latitude, 
position . coords . longitude) ; 

if (map) { 

map.panTo(pos); 

} 

else { 

module. init(poSj zoomLevel ? zoomLevel : 15); 
} // if..else 

findResources(f unctionO { 
module. updateDisplay O; 

}); 

}, 

nullj 
{ 

enableHighAccuracy : true 

}); 

} // run 

var module = { 
run: run, 

}; 

return module; 

})(); 

The run function defined in the preceding code is exposed through the MOUNDZ module 
and provides a simple interface for setting up the Geolocation watchPosition method. 

The watcIiPosition method provides a mechanism for us to access the user's position, 
and then to continue to monitor the position for changes. By monitoring the user's 
position, we will be able to update the display as they move around, which is idea! when 
building games and other such interactive applications. 

I NOTE: As mentioned in Chapter 1 , there is overhead involved when regularly accessing a 
I device's current position. So, while the preceding code is effective at monitoring the user's 
I position accurately, iťs important that we provide the ability to turn it off to allow people to 
conserve battery lite on their mobile device. 

Notice that in the preceding code we obtain an ID that relates to the position watch that has been 
created, and we will be able to use this later to stop monitoring the location. 



While the watchPosition method differs in the number of times that the callback passed 
to it will be executed, the data returned in tine callbaci< is identical to tlie 
getCurrentPosition metinod, whicli we investigated previously. Basically, the 
watcIiPosition nnethod will be called until the clearWatch method is called, whereas 
getCurrentPosition will execute once and once oniy. For instance, in the preceding 
code, the value that we assign to the posWatchld variable couid be passed to the 
clearWatch function, and we wouid stop receiving location updates. 

Additionally, the error callback and options parameters are the same. In this particular 
case, we supply the enableHighAccuracy option as true to indicate to the device that we 
wouId like to use the GPS in the device, rather than just using network triangulation. 

In the callback within our run function, we simply map the returned latitude and 
longitude into a google. maps. LatLng object, and then pass that to our map as the 
position that we wish to use. As our f indResources function works with the current 
center position of the map, all we have to do is call it once the position changes (and we 
have updated the map position to match), and relevant resources will be returned for our 
current location. 

f ^ 

NOTE: While building location-based services and applications is interesting, testing them can be 

a challenge. Often it is a case of writing some code, and then taking a device out into the field to 
ensure that the code is behaving as expected. If you find a problém, then iťs back to the desk to 
tweak the code. Then you rinse and repeat until everything works as expected. 

Android actually offers some better-than-average tool support for building and testing 
geolocation-based applications. For more Information on how to use the Android debug tools to 
simplify your development experience, including how to simulate GPS information and paths, 
have a look at the following article: i 

http://xpmobi.org/tutorials/android-emulator-geolocation-testing.html 

The downside, though, is that, without using these tools, the emulátor will not return any useful 
position information, and you will see a blank screen. So, if you don't have experience using the 
tools, or you don't have an Android device that you can test with instead, we wouId recommend 
working through the article and then carry on after that. 

If you have a working Android device or have simulated geolocation events in the 
emulátor when running the application, you shouid now see screens similar to the ones 
shown in Figuře 1 0-1 1 . The first of the screen captures shows the permission dialog that 
is displayed when the application requests the user's position, and the second shows 
the screen once permission has been granted. 
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Figuře 1 0-1 1 . With geolocation data simulated in tiie emulátor, you stiouid see results similar to the images 
above. 



With the application now tracking our position and providing information on resources 
around us, iťs time to implement sonne more of the game functionality. 



Implementing a User Login 

Up until now, nothing in the game has required any l<nowledge of the user, but we are 
getting to the point where the user will probably want to mine some resources to start 
building their base. 

Additionally, iťs unlil<ely that we'll want to allow a user to walk around with a limitless 
amount of resources, so we are going to need to implement some limits. While the 
Geominer API will take care of most of the work for us, we are going to need to maintain 
a session key on the client, which we will include with any requests that need 
information on who the current user is. 

While the Geominer suitě of tools couid implement its own username and password 
management to meet this need, iťs definitely not the optimal solution. A much better 
solution is to integrate with an existing API that many users find themselves using on a 
day-to-day basis. As shown previously in Figuře 10-7, the Twitter API 
(http://dev.twitter.com) has been chosen to meet this need in version 1 of Geominer. 

In the future, additional authentication options will most likely be added, including other 
sociál networks such as Facebook and the geosocial networks that actually provide the 



242 



CHAPTER 10: Integrating with Sociál APls 




check-in data. For the moment, though, Twitter provides a good middle ground in terms 
of an easy-to-implement solution with a reasonably strong existing user base. 

NOTE: You may be wondering why Twitter was chosen as tfie autlientication provider when the 
Geominer API presumably aiready tall<s to geosocial networl<s such as Gowalla and Foursquare. 
This is a fair question, given that both of those networl<s offer authentication support through 
their APls. Primarily, this is because those geosocial networks still do not have as large a user 
base as Twitter. 

Geosocial games like Moundz may interest users outside of the current geosocial networking 
users, SO it is desirable for people to be able to access the game without needing a user account 
on a specific geosocial network. In many respects, Twitter is neutral ground. 

We now have a design decision to make: do we ask someone to log in at the point that 
authentication is required (i.e., when they start to collect resources), or do we create a 
weicome page and ask them to log in right from the start? There are definite merits to 
both Solutions, and, while many wouid argue that from a usability perspective it wouid 
be better to leave logging in oniy until required, for the sake of simplicity we will build a 
simple application splash screen with a very clear "Sign in with Twitter" button. 



Constructing the Weicome and Login Screen 

Creating a weicome screen for our application is a reasonably trivial exercise (as far as 
the appearance goes, anyway). First, ieťs modify the HTML of the index.html file: 

<!DOCTYPE htrtil> 

<html> 

<head> 

</head> 

<body onload="initialize()"> 
<div id="splash"> 

<strong>Welcome to</strong> 

<mg src="img/[noundz_logo.png" /> 

<p class="hint"> 

Press the 'Sign in with Twitter' button below to get started playing. 

</p> 

<span id="login"></login> 
</div> 

<div id="app"> 

</div> 

</body> 

</htrtil> 

The modifications to the HTML are simple, with the onIy real point of note being that the 
#splash div has been added as another top-level container alongside the #app div. The 
Moundz logo image used on this page can be downioaded from prowebapps GitHub 
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repository at the following URL: https://github.com/sidelab/prowebapps- 
code/tree/master/moundz/img. 

As usual, without any CSS styling applied, the screen is pretty ugly. Figuře 10-12 shows 
an example of the screen layout without any CSS applied. 
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Figuře 10-12. The weicome screen without any CSS 



Leťs sort that situation now by adding the following CSS to the moundz.css filé: 

/* application window styles */ 

#app { 

height: 100%; 
width: 100%; 
display: none; 

} 

/* splash screen styles */ 

#splash { 

height: 100%; 
width: 80%; 

bacl<ground: -webl<it-gradient(linear, left top, left bottom, from(#c4c8b7) , 
to(#cddd87)); 

padding: O 10%; 

} 

#splash > * { 

display: blocl<; 
margin: O auto; 
text-align: center; 
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} 



#splash strong { 

color: hsla(0, 10%, 30%, 0.6); 
font-size: 2.0em; 

text-shadow: hsla(0, 10%, 90%, 0.8) O ipx Opx; 
padding: 20px 0 0 0; 

} 

#splash p.hint { 

-webkit-border-radius: 4px; 
background: hsla(0, 10%, 30%, 0.5); 
margin: 5px; 
padding: lOpx I5px; 
color: white; 
font-size: O.SOem; 

} 

#login { 

position: fixed; 
width: 80%; 
bottom: 20px; 

} 

With this CSS active, the weicome screen is displayed in a mucin more presentable 
fashion, as sliown in Figuře 10-13. 
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Figuře 1 0-1 3. With the CSS applied, we have a more presentable weicome screen. 



OK, the weicome page is done. Don't worry that the actual "Sign in with Twitter" button 
is absent— we'll tal<e care of that soon. 



For the most part, the CSS implemented here has been discussed before, so we won't 
go into any great detail on what has been done to lay out the weicome screen. One 
aspect that we haven't looked at, however, is the use of the hsla color function to 
specify coloring for various elements on the page. 

The hsla function takés values for hue, saturation, lightness, and alpha, and offers an 
alternativě to specifying colors using the nnore common rgba (for red, green, blue, alpha) 
function. While we won't go into great depth about how to use the hsla scheme, there 
definitely are sonne great benefits to using it, so iťs weil worth investigating if you have 
the time. For more information on the topič, the article at the following URL provides a 
great introduction: http://css-tricl<s.com/yay-for-hsla. 



Twitter Anywhere and the Login Process 

The process for adding a third-party authentication service to your application is easy in 
some respects, but can also be pretty painful in other ways. With mobile web apps 
being very much a minority group at the moment, we don't exactly have solutions that 
are tailor-made for our requirements. 

The current mechanism for providing authentication services to an API such as Twitter 
centers around a standard called OAuth (http://oauth.net). OAuth provides a robust 
authentication mechanism that prevents users from having to supply their username and 
password to the application using the service. It does, however, come with some 
complexity. The process of authenticating via OAuth involves directing your users to the 
third-party service, which then asks the user to grant permission to your application. 

In the oase of Moundz, we will not ask users to provide Moundz with a username and 
password, but rather direct them to Twitter. If they are aiready logged into Twitter, then 
they will be asked permission for Moundz to use their Twitter account. If they accept, 
then they'll be logged into Moundz successfully. 

Leťs look at implementing that using the Twitter Anywhere JavaScript libraries 
(http://dev.twitter.com/anywhere). Following the instructions in the Twitter Anywhere 
Getting Started documentation (http://dev.twitter.com/anywhere/begin), the first thing 
to do is to create an application. This can be done by visiting the following URL: 
http://dev.twitter.com/anywhere/apps/new. 

The registration screen is shown in Figuře 10-14, and you can see that most of the 
details asked for are pretty obvious, with the exception of the callback URL. For this 
field, supply the domain that you think you will deploy the application to eventually. The 
information is used as part of the authentication process. 



NOTE: If you like, you can avoid creating a new application for now, and instead use the existing 
Moundz key that has been created to work through the sample code. Then you can create your 
own application later. 
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Figuře 1 0-1 4. Registering anew application with Twitter is relatively simple, but feel free to use the sample key 
and complete the process later. 



We now move on to prepping our application for Twitter Anywhere integration. TIne next 
steps are including the required JavaScript library in our index. Iitml page and 
instructing tine Twitter Anywinere library to create a login button in our designated #login 
area. 

<!DOCTYPE htinl> 

<html> 

<head> 

<script type="text/javascript" src=" http ://maps. google. com/maps/api/js?sensor=true"> 
</script> 

<script type="text/javascript" 

src="http://platform. twitter. com/anywhere.js?id=K7BhAacKov80oFwEHYRU7Q8iv=l"> 
</script> 

<script type="text/javascript"> 

twttr.anywhere(f unction (T) { 
T( "#login " ) . connectButton( ) ; 

}); 

</script> 

<script type="text/javascript"> 
function initializeQ { 
MOUNDZ.runO; 



} // initialize 

</script> 

</head> 

<body onload="initialize()"> 

</body> 
</html> 

The inclusion of the script is shown in bold in tlie preceding code, using the IVloundz 
application sannple l<ey. This shouid create a nice login button at the base of the screen 
(after a little browser activity). The result is displayed in Figuře 10-15. 
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Figuře 1 0-15. A Connect with Twitter button shouid appear on the Moundz weicome screen. 

To log into your application, click the Connect with Twitter button. At this point, the user 
experience of the Twitter Anywhere solution starts to go downhill for mobile devices. 
Figuře 10-16 shows the resulting login screen at Twitter. 
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Figuře 10-16. When directed to the Twittersite forlogin, we receive a desktop login/permission screen. 



We'll want to avoid presenting the user a non-mobile-optimized screen and, while there 
is little we can do about it here, we will investigate an alternativě approach later in the 
chapter. 

Once a user has completed the login process (or the permission-granting process, if theyVe 
aiready logged in), they will be returned to the application screen. As Twitter Anywhere 
opens a new window for the authentication process, this new window will simply be dosed. 
The Moundz weicome screen shouid now appear similar to Figuře 1 0-1 7. 
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Figuře 1 0-1 7. Once you complete the authentication process with Twitter, the login button is replaced witli a 
"Connected with Twitter" image. 



From here, all that is left to do is to bind to event handlers provided in the Twitter 
Anywhere API so our web page can respond to the authentication process completing 
successfully. Handling these events is covered in detail in the Twitter Anywhere 
documentation (http://dev.twitter.eom/anywhere/begin#login-signup). While 
innplementing this wouid probably be the sinnplest way to provide the login functionality 
for our application, unfortunately it has some drawbacks: 

■ As demonstrated, the login screen provided by Twitter for our users is 
not optimized for mobile, and this provides a poor user experience. 

■ The generic Twitter Anywhere authentication process requires a 
callback URL to complete successfully. While this works weil for 
mobile web applications that are deployed to a web server, it doesn't 
work for PhoneGap-wrapped mobile applications. These applications 
are run from a file-based URL (as discussed earlier in the chapter), 
which prevents the Anywhere API from completing its signin process. 

While the first issue is cosmetic, the second is a bit of a deal breaker. Not having the option to wrap 
an application for native deployment cuts you off from a large portion of your potential application 
market. We need an alternativě. 



250 



CHAPTER 10: Integrating with Sociál APls 




NOTE: You will likely encounter an additional issue if you have a server-side component to your 
application that is attempting to manage some application statě, which is the case in Moundz. 
While transmitting your users' Twitter IDs to the server to assist with managing that statě won't 
exposé them to any great risk, this isn't the most robust soiution. Thankfuily, the Twitter API 
team is aiready on the case, and has provided a mechanism called Bridge Corfefor bridging 
between the client and server. IVlore Information can be found on implementing this in 
presentation at the following URL: 

http://slideshare.net/themattharris/twitterapi-at-socialapp-workshop- 
4829546. 



Alternativě Twitter Autlientication via Geominer 

It wouid have been wonderful if we couid fiave used the Twitter Anywhere API for our 
application, but, as we want to package the application for marketplace distribution 
using PhoneGap, that is off the table— at least for the nnoment. In this section, we will 
investigate implementing some alternativě authentication using some helpful parts of the 
Geominer API. 

Leťs start by including the Geominer JavaScript library into index.html, replacing the 
previous Twitter Anywhere references: 

<!DOCTYPE htitll> 

<html> 

<head> 

<script type="text/javascript" src="http: //maps. google. com/maps/api/js?sensor=true"> 
</script> 

<script type="text/javascript" src="http ://api. geominer. net/jsapi/vl/geominer.js"> 
</script> 

<script type="text/javascript"> 
function initializeO { 

MOUNDZ. init O; 
} // initialize 
</script> 
</head> 

<body onload="initialize()"> 

</body> 
</htinl> 

Next, leťs wire the Geominer initialization the MOUNDZ. init function: 
MOUNDZ = (functionO { 



// initialize variables 
var geominer = nullj 

posWatchld = 0; 



function gotoPosition(position, zoomLevel) { 
// define the required optlons 
var myOptions = { 

zoom: zoomLevel ? zoomLevel : DEFAULT_ZOOM, 

center: position, 

mapTypeControl: falše, 

streetViewControl: falše, 

mapTypeId : google . maps . MapTypeId . ROADMAP 

}; 

// initiallze the map 
map = new google. maps. Map ( 

document . getElementByld ( "map_canvas" ) , 

myOptions); 
} // gotoPositlon 



var module = { 

init: function(zoomLevel) { 

// initiallze the geominer bridge 
geominer = new GEOMINER. Bridge({ 
app: 'moundz', 
login : ' #login ' 

}); 

$(geominer).bind('authenticateď, function(evt) { 
$('#splash').hide(); 
$('#app'),show()j 

run(zoomLevel); 

}); 

// initiallze the screen 
initScreen(); 



}; 

return module; 

})(); 

We have made a few changes to the MOUNDZ module here, which in addition to wiring 
the Geominer JavaScript API heips to reorganize things a little: 

1. The previous contents of the MOUNDZ. init function have been moved to a new 
internal function called gotoPosition. 



2. A new module variable, geominer, is defined at the beginning of the module. 
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3. The geominer variable is initialized with a new GEOMINER.Bridge object as part of 
the refined init function. At this stage, the bridge is created and two parameters 
are specified— the name of the app that we are running now (the Geominer API 
has been built to support multiple apps) and the login container that will receive 
the login button (as per the Twitter Anywhere initialization). 

4. Finally, we use the jQuery bind function to listen for "authenticated" events, which 
flag to US that a user has completed the login process. In response to this event, 
we will close the weicome screen and display the main application view. 

Very little code is actually required to implement the connectivity within the MOUNDZ 
module, and this is due to the behind-the-scenes work that the Geominer API is doing 
for US. If you are interested, we encourage you to check out the source code for the 
Geominer JavaScript API, at http://api.geominer.net/jsapi/vl/geominer.js. 

If everything has gone according to pian, we shouid have a slightly different login 
experience now. Figuře 10-18 shows the updated login screen, which is quite similar in 
appearance to the Twitter Anywhere version. 
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Figuře 10-18. The weicome screen using the Geominer API 

While the initial weicome screen looks similar, the process will differ from this point 
forward. Figuře 10-19 shows the mobile-optimized permissions screen that we receive 
while using the established server-side APls (via Geominer) rather than Twitter 
Anywhere. 
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Figuře 10-19. Using the more established Twitter RESTful API provides a better mobile experience. 



Given that we accept the connection to Twitter, we will be returned to our application via 
the Geominer API. While this is going on, the client-side Geominer API script that we 
included is monitoring the login process, and, once it has determined that the process 
has completed successfully, the weicome screen is hidden and the user is taken to the 
main application screen as per earlier in the application. 




NOTE: One aspect of this solution that is not as elegant as using Twitter Anywhere is that the 
application is shown as "Geominer" rather than "Moundz" when we are going through the 
authentication process. While future versions of Geominer may use different OAuth parameters to 
show the request as coming from an application rather than itself, the current version doesn't. 





If you are looking to build an application that is not a geosocial game, but you are 
interested in how we implemented the alternativě login mechanism using Geominer, 
then it is probably worthwhile to fork the Geominer project on GitHub, which can be 
found at the following URL: https://github.com/sidelab/geominer. 



Summary 

In this chapter, we have looked at some of the challenges around integrating with third- 
party APls that are currently available. Using these APls is still very important given the 
benefits that they bring to applications that work with them; however, at this stage, most 
are geared toward server-side integration or native desktop and mobile development. As 




such, we looked at ways to work around the limitations in the current APls while giving 
mobile web apps tlie opportunity to access tliose APls. 

We then moved on to looking at how to add authentication into a mobile web 
application using Twitter as an authentication service. Once again, while this appears 
simple, particular use cases required in mobile web apps can make the standard 
integration path less effective. We investigated alternativě solutions to counter current 
limitations in this regard as weil. 

In the next chapter, we will use the work we have done in this chapter to allow the 
players to interact with the game, now that we have the ability to manage our game 
State via some user Information. Additionally, we will polish up Moundz and get it ready 
for distribution to the Android marketplace by once again making use of PhoneGap. 




Mobile Ul Frameworks 
Compared 

Before we get into the finál stages of preparing our application for packaging for the 
Android marketplace, iťs worth taking some time to practically compare the various 
mobile frameworks that are available right now. During the time it has taken to write this 
book, about three new frameworks have come onto the scene, and without doubt there 
will be others still. 

While it has been important to understand the fundamental bullding blocks for building 
mobile web applications, it is also important to consider what tools and frameworks are 
available that make our lives easier. 

In this chapter, we will look at some of the mobile Ul frameworks that are becoming 
popular. We will do this by taking the current Moundz Ul and converting it to each of the 
frameworks, which shouid provide a feel for how the various Ul frameworks operáte and 
also how they differ from working with a bare-bones HTML Ul. 

Mobile Ul Frameworks Overview 

Getting started with mobile frameworks can be a little overwhelming, and choosing the 
right one can feel like a mammoth task. This is definitely compounded by the fact that, 
when building an app for the mobile Web, you may focus on building your application 
for one device without really knowing what other devices might end up using it 
eventually. So, when you choose a framework, you want one that is going to work weil 
on as many of those devices as possible. 

The worid of mobile Ul web frameworks is moving pretty fast at the moment. When we 
started writing this book, oniy one of the four frameworks that we are covering here 
(jQTouch) was even released. Additionally, at the time of writing, Sencha Touch was the 
onIy framework to have reached a stable 1 .0 release. 
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NOTE: The list of frameworks that we looked at in this book is not exhaustive, and ttiere are 
some excellent frameworks in addition to tiiese. If you are interested in otiier frameworks tiiat 
are available, or don't find a framework to fit your needs in this chapter, then the following URL 
may be worth a look: www.xpmobi.org/mobile-ui-frameworks. 



Similarities and Differences Between Frameworks 

In this chapter, we will be taking a look at Jo, jQTouch, jQuery Mobile, and Sencha 
Touch. For each of these frameworks, we will take a simplified version of our IVIoundz 
application and modify it to suit the framework. As mentioned in the chapter 
introduction, this will give you a good feel for the differences between each of the 
frameworks, and shouid assist you in choosing a framework that suits you in your future 
Android web app projects. 

At a conceptual level, each of the frameworks is fairiy similar: 

■ Each provides a mechanism for supporting multiple mobile application 
"pages" without the need for reloading these pages from the server. 
Given the limited screen real estate on a mobile device, it is normál for 
mobile applications to contain twice as many application pages as a 
desktop equivalent. 

■ When you consider the preceding point combined with the higher 
latency of mobile broadband, one of the most important things that a 
mobile Ul framework can provide is an effective way to assist you in 
managing high-latency situations. 

■ Each provides a level of Ul customization to help mobile web apps feel 
more like native apps. The challenge here is making a web application 
feel consistent with the native feel of a multitude of devices. 

When it comes to how each of the frameworks is implemented, however, things start to 
differ. The biggest difference is around whether a framework uses a markup-based 
approach or is more declarative in the way the Ul is created. We'll briefly explore these 
two concepts before looking at each of the frameworks individually. 



Markup-Based Ul Frameworks 

In a markup-based Ul framework, you commoniy define the Ul layout using pure HTML 
with CSS classes (or alternativě attributes in the HTML) that influence the behavior of the 
frameworks. 

In the cases where CSS is used to control this behavior (jQTouch, for example), the CSS 
classes serve to influence the look and feel of the application through stylesheets, and 
additionally to provide guidance to the accompanying JavaScript on how to handle 
those elements programmatically. 



When an alternativě attribute is used (jQuery Mobile adopts a suitě of data attributes— 
see www.w3.org/TR/html5/elements.html for more information), tinese attributes are 
postprocessed by tine JavaScript, and tlie appropriate CSS classes are applied (winere 
required). 

Declarative Ul Frameworks 

Using a declarative Ul framework is quite different from the nnarkup-based experience. 
Whereas in the markup-based approach you wouid start first with your HTML (and 
possibly CSS), in a declarative framework iťs all about the code. The Ul elements are 
declared and defined, and programmatically added to the Ul. 

Finding Your Own Best Fit 

The choice between a markup-based or declarative Ul framework very much comes 
down to personál preference. For this reason, we really will try to avoid making strong 
recommendations for one framework over another. If you haven't done a lot of work with 
JavaScript before, then it is likely you will be open to different approaches; in this case, 
we wouId recommend trying a few and seeing what is a better fit for you. 

If, however, you have worked with HTML and JavaScript previously, then you might 
have a preference one way or another aiready. In this case, you can focus first on the 
two frameworks that match your currently preferred style, and, if you don't find a good 
fit there, you can take a look at the other two. 

Given our extensive use of jQuery throughout the book aiready, it will probably come as 
no surprise that beyond this chapter we will continue to work with jQuery Mobile. This 
shouid not be taken as a rubber-stamping of jQuery Mobile as the best framework 
looked at here— rather, it is simply the best fit for the exercises in this book. This chapter 
is provided primarily to assist you in finding your own best fit. 

Setting Up for the Framework Comparison 

Before we get started on the challenge, leťs simplify some of the Moundz source code 
SO we don't have to go through the Twitter authentication step or location detection 
(which can be pretty frustrating in the emulátor). 

To do this, we will need to make some modifications to the Moundz source files. 
Comment out (or remove) the splash screen div element in the index.html file; 

<!DOCTYPE html> 

<html> 

<head> 

</head> 

<body onload="initialize()"> 
</-- 

<cliv id="splash"> 

< strong >lflelcome to</strong> 




<img src="img/moundz_logo.png" /> 
<p class="hint"> 

Press the 'Sign in uith Tuitter' button bélou to get started playing. 

</p> 

<span id="login"></span> 
</div> 

--> 

<div id="app"> 

</div> 

</body> 

</htitil> 

Next, we need to make some modifications to the moundz. js file that will make the 
process of testing the various mobile frameworks less painful. 

Firstly, locate the run function and provide an ability to specify a mock location. This 
comes in the form of a second, optional parameter that we can pass to the run function. 
When the second parameter is supplied, location detection will be bypassed and that 
location will be used instead. 

function run(zoomLevel, mockPosition) { 

// check that the watch hasn't already been set up 

// if it has, then exit, as we don't want two watches... 

i-F (posWatchld !== O) { 

return; 
} // if 

// if mock positionj then use that instead 
if (mockPosition) { 

gotoPosition(mockPosition, zoomLevel ? zoomLevel : 15); 

f indResources(f unctionO { 
module. updateDisplay O; 

}); 

} 

else { 

// create the watch (originál non-mock code) 
posWatchld = navigátor. geolocation.watchPosition( 
f unction(position) { 

var pos = new google. maps.LatLng( 
position . coords . latitude j 
position . coords . longitude) ; 

if (map) { 

map.panTo(pos); 

} 

else { 

gotoPosition(pos, zoomLevel ? zoomLevel : 15); 
} // if..else 

findResources(f unctionO { 
module. updateDisplay O; 

}); 

nullj 
{ 

enableHighAccuracy : true 



}); 

} // if..else 

} // run 

Next, modify the MOUNDZ.init function and comment out the authenticated event 
handler. Additionally, pláce a call to the run function in tlie main body of tlie init 
function SO tine application initializes properly. 

MOUNDZ = (functionO { 



var module = { 



init: f unction(zoo[nLevel) { 

// initialize the geominer bridge 
geominer = new GEOMINER. Bridge({ 

app: 'moundz', 

login: '#login' 

}); 
/* 

$(geominer).bind(' authenticated', function(evt) { 
$('#splash').hide(); 
$('#app').show(); 

run(zoomLevel) j 

}); 

*/ 

// initialize the screen 
initScreenO; 

// run the application 

run(zoomLevel, new google. maps. LatLng(-33. 86, 151.21)); 



return module; 

})(); 

AI! rigiit, we're almost tinere. Finally, mal<e ona simple change to tine moundz.css file to 
have tine #app div display on application start by default. 

/* application window styles */ 

#app { 

height: 100%; 

width: 100%; 

/* display: none; */ 

} 

While we may need to modify this CSS later when integrating the various frameworks, it 
wouid be nice to know that the code for our starting point works correctly. If everything 
is going to pian, your Moundz application shouid start up and resemble Figuře 11-1 . 
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Figuře 11-1. The baseline Moundz app, ready for Ul framework testing 



We now have Moundz at a suitable baseline ready for our frannework comparison. Now 
make copies of the modified source into four directories— one for each of the 
frameworks that we are going to compare. Figuře 11-2 sliows an example structure. 
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Figuře 11-2. The folder structure for the Ul framework comparison- 
each of the frameworks 



-one base directory and one directory for 



This structure will serve you weil if you wish to maka comparisons against the 
frameworks. The completed code for each of the frameworks is available from the 
following URL: https://github.com/sidelab/prowebapps- 
code/tree/master/frameworks/challenge. 



NOTE: If you wouid prefer to have a quick look at any one of the frameworks rather than work 
Jthrough each separately, then accessing the code from the GitHub repository can be very usefu 
jditionally, it might give you a feel for which of the frameworks you have a preference for, an| 
|n then have a look at that particular framework in more depth. 



Jo 

The first framework that we will be having a look at is Jo. Jo follows a declarative style 
and offers a lightweight but rich framework for developing mobile applications. The 
following list gives some important information about Jo: 

■ Framework: Jo 

■ Style: Declarative 

■ l/l/eb s/ře: http://joapp.com 

■ License: Open source (OpenBSD) 

■ Source code: https://github.com/davebalmer/jo 

■ Requirements: None 

The following list describes some of Jo's strengths: 

■ Jo comes with excellent documentation. In fact, the author of Jo (Dave 
Balmer; http://twitter.com/balmer) created aspecialized 
documentation tool (JoDoc) for creating higher-quality JavaScript API 
documentation. 

■ Jo is built for a multidevice environment. It has been built for and 
tested on a wide variety of devices that support HTML5 and CSS3 
(iOS, Android, webOS, and Symbian). 

■ Jo is extremely lightweight with regard to slze, and, since Jo has no 
dependencles on other JavaScript libraries, your application will 
probably be smaller using Jo than any other mobile Ul framework. 

■ Jo plays nicely with other JavaScript libraries (including jQuery). 



The following are some of its weaknesses: 



■ Its library is not as feature complete as some of the other mobile Ul 
frameworks (on the other hand, iťs a great open source project to get 
involved with if you're interested in contributing). 

■ Its Ul look and feel is not quite as polished as other frameworks. 



Getting Started with Jo 



First, we will downioad a distribution of Jo from the web site (http://joapp.com). At the 
time of writing, the latest stable version is 0.3.0, but there may weil be a later version by 
the time you read this. If that is the oase, you shouid be able to access version 0.3.0 
from the downioads area on GitHub (https : //github . com/davebalmer/ jo/downloads). 

Alternatively, you can downioad a more recent version and just adapt the code to cater 
for any changes (usually changes are pretty mlnor, and Jo has great documentation so it 
shouid be very simple). 

Once you have downioaded a distribution of Jo, unzip the archive. You shouid see a 
directory structure similar to that displayed in Figuře 11-3. 
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Figuře 11-3. The structure of the Jo distribution 



If you wouid like to see the kind of things that Jo can do, then feel free to open the 
test.html file in the samples directory and play with the Kitchen Sink demo. 



Moving back to Moundz, we need to copy the css and js directories from the Jo 
distribution into the Moundz directory we have set up for the framework comparison. 
per earlier instructions, copy these files into the directory created for the IVloundz Jo 
sample. Figuře 11-4 shows a sample of how that directory structure will look. 
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Figuře 1 1 -4. The required Jo resource files are added to the Moundz Ul challenge folder. 



Finally, before we get stuck into the detail, leťs add the required includes into the 
index . html file for IVloundz: 

<!DOCTYPE html> 

<html> 

<head> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 

<!-- <link rel="stylesheet" media="screen" href="moundz.css" /> --> 

<link rel="stylesheet" řnedia="screen" href="css/jo.css" /> 

<script type="text/javascript" src=" jquery-l.4.2.min. js"></script> 

<script type="text/javascript" src=" js/jo. js"></script> 

<script type="text/javascript" src="moundz. js"></script> 

<!-- <script type="text/javascript" src="phonegap. js"></script> --> 

<script type="text/javascript" src="http: //api. geominer.net/ jsapi/vl/geominer.js"> 

</script> 

<script type="text/javascript" src="http: //maps. google. com/maps/api/js?sensor=true"> 
</script> 

<script type="text/javascript"> 
function initializeQ { 

MOUNDZ. init(); 
} // initialize 
</script> 



</head> 

<body onload="initialize()"> 

</body> 
</html> 

Essentially, include css/jo.css and js/jo. js using suitable HTML and Jo will be 
available for you to use in moundz. js (this is covered in the next section). Additionally, to 
prevent any CSS conflicts, comment out tine moundz. css file. 

Moundz, Meet Jo 

As Jo is a declarative Ul framework, most of the existing HTML that we liave needs to 
be removed. By making appropriate Jo calis (a surprisingly succinct amount), suitable 
HTML will be generated. So, first things first, remove the HTML that is shown in bold 
and italicized in the following code sample: 

<!DOCTYPE html> 

<html> 

<head> 

</head> 

<body onload="initialize()"> 
<!-- DELETE FROM HERE 
<div id="app"> 

<hl class="simple floating">Moundz</hl> 

<div id="inap_canvas" style="uidth:lOO%j height:lOO%"></div> 

<div id="marker-nav"> 

<img src="img/navigation-arrou.png" class="left disabled" /> 
<span class='marker-title' >Test Text</span> 
<img src="iing/navigation-arrou.png" class="right" /> 
</div> 

<div id="marker-detail" class="child-screen"> 

<div class='content' >Some Test Content</div> 

<button class= 'close ' >Close</button> 
</div> 
</div> 

TO HERE (or just leave commented out) --> 

</body> 
</html> 

After the code has been removed (you can also remove the earlier splash page HTML as 
weil) or commented out, we are left with an HTML document that contains an empty 
body tag. This is the ideál blank canvas with which Jo likes to work. We will now hand it 
over to Jo to create the required elements. We do this by replacing the code in the 
initScreen function with the following code (and defining a few extra variables): 

MOUNDZ = (functionO { 

// initialize constants 
var DEFAULT_ZOOM = 8, 

GEOMINER_MOUNDZ_URL = 'http://api.geominer.net/vl/moundz'; 

// initialize variables 
var geominer = null. 



// new jo variables 
Container = null, 
mapCard = null, 
detailCard = null, 
resourceButton = null, 
navbar = null, 
stack = null, 
toolbar = null, 
map = null, 

posWatchld = 0; 



function initScreenO { 
var stackHeight; 

jo.loadO; 

// create a stack that we will use for paging 
stack = new joStack(); 

// create the navbar for the app 
navbar = new joNavbar('Do Moundz'); 
navbar .setStack( stack); 

// define the resource details button 
resourceButton = new joButton("Resource"); 

// attach the select event handler 
resourceButton. selectEvent.subscribe (function O { 

// when the button is pushed, then show the detail page 

stack. push (detailCard); 

}); 

// create the toolbar 
toolbar = new joToolbar([ 
new joFlexrow([ 

new joButton("Previous").selectEvent.subscribe(function() { 
activateMarker(markers[markerIndex - l]); 

}), 

resourceButton, 

new joButton("Next").selectEvent.subscribe(function() { 
activateMarker(markers[markerIndex + l]); 



// create the wrapper to the body 
Container = new joScreen([ 

navbar, 

toolbar, 

stack 

]); 



// now that the screen is created, calculate the available height 
stackHeight = stack. container.getBoundingClientRect() .height - 




toolbar. Container .getBoundingClientRectO .height - 
navbar .Container .getBoundingClientRect O .height; 

// create the map card 
mapCard = new joCard([ 
joDOM.create( 'div' j { 

id: 'mapcanvas' , 

height: stackHeight + 'px' 



// create the detail card 
detailCard = new joCard(); 

// add the map to the view 
stack.push(mapCard); 
} // initScreen 

})();" 

Leťs now walk through whaťs happening step by step: 

1. Firstly, we tell Jo that we are ready for it to initialize with a call to jo.load(). 

2. Then we create a new joStack that is used to handle paging in the application. A 
stack is typically made up of multiple joCard objects, but this isn't a hard-and-fast 
rule. 

3. Next, we create a joNavBar, which will provide our application a title bar and 
handle displaying a back button at the appropriate time (for example, when more 
than a single card has been added to the stack). We then also create a joToolbar, 
which will contain our buttons for navigating through the markers. 

4. With our top-level controis defined, we then move on to telling Jo where to put 
these controis. This is done by creating a joScreen object and passing it our two 
controis in an array. At this point, we have an interface that we can work with, but 
we don't have our map. 

5. To add our map, we create a new joCard to hold our map. We're working at a 
lower level here than we usually wouid for a Jo application, by accessing the 
joDOM utility to manually create the div within which Google Maps will generate 
the map. 

6. After creating the card for the map, we create one more joCard, which will be 
used to show the detail for a search result. 

7. Finally, we push the map card that we created (in step 5) to the stack (created in 
step 2). 

The process is quite logical, and having built mobile Uls from scratch you shouid have a 
pretty good understanding of what is going on. In addition to the preceding steps, it is 
worth noting the following also: 



■ As the map does not display weil using the previous instructions of 
100 percent height and width, we need to calculate the height that we 
shouid specify the map to. We do this by calculating the available 
height in the stack, and then subtracting the height of the navbar and 
toolbar from the total. 

■ Additionally, note that, when we create our button, we use Jo's 
subscribe method to attach to the selectEvent of each of the buttons. 
The subscribe method in Jo is quite similar to the bind function in 
jQuery. 

Once all of that is completed, we have a screen that resembles the image shown in 
Figuře 11-5. 
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Figuře 11-5. The Moundz application interface created in a Jo web app 



We are now almost finished with our Jo sample. All that is required to make the 
application behave as it shouid are some changes to the activateMarker function, as 
shown in bold in the following code: 

MOUNDZ = (functionO { 

// initialize constants 
var DEFAULT_ZOOM = 8, 

GEOMINER_MOUNDZ_URL = 'http://api.geominer.net/vl/moundz'; 

// initialize variables 
var geominer = nullj 

markerindex = O, 

posWatchld = 0; 




/* priváte functions */ 

function activateMarker(rtiarker) { 

// iterate through the markers and set to the inactive image 
for (var ii = 0; ii < markers. length; ii++) { 

markers [ii] .setIcon( ' img/pin-inactive.png' ); 
} // for 

// update the specified marker's icon to the active image 
marker.setIcon( ' img/pin-active.png' ); 

// update the text of the resource button 
resourceButton . setData (mar ker . getTitle ( ) ) ; 

// update the contents of the detail card 
detailCard . setData (markerContent [marker . getTitle() ] ) j 

// get the updated active marker index 
markerindex = getMarkerIndex(marker)j 

} // activateMarker 

})();" 

While we leave the marker updating in the activateMarker function, we remove all of the 
other existing content and replace it with three simple calis: 

1. We update the text of the resource button using Jo's setData method. 

2. We update the contents of the detailCard once again using the setData method, 
which gives us some nice consistency. 

3. We then save the value of the current marker index to the markerindex variable 
(also note the variable definition in the module scope). This fina! step allows our 
Next and Previous button handlers to operáte correctly. 

At this point, we shouid have a sample Jo web app that functions as per our previous 
hand-constructed Moundz Ul. Figuře 11-6 shows an example of the expected display. 
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Figuře 1 1 -6. Our Moundz application converted to a Jo web app 

WeII, thaťs one down and three to go. Our next framework is jQTouch, which is a 
markup-based Ul framework. It will be interesting to compare the two approaches. 



jQTouch 



As mentioned previously, when writing first began on this book, jQTouch was the oniy 
framework of the four investigated here that was actually released. In many ways, 
jQTouch demonstrated what couid be achieved using web technologies to create 
native-like interfaces for mobile devices. This included using WebKit animations to 
produce very fluid interfaces. 

■ Framewor/c: jQTouch 

■ Style: Markup based 

■ lA^eb s/ře: http://jqtouch.com 

■ License: Open source (MIT) 

■ Source code: https://github.com/senchalabs/jOTouch 

■ Reqty;femenřs:jQuery 

The following are some of jQTouch's strengths: 



■ It is the most established of the frameworks looked at in this chapter, 
and has good community resources. 



■ It contains a large variety of weil-implemented page transition effects. 



■ Its familiar jQuery experience is a plus for those experienced with 
jQuery. 

The following are some of its weal<nesses: 

■ Updates to the stable releases of the library are very infrequent; 
however, the GitHub repository is updated regularly. 

■ With change of library maintainer under the Sencha Labs transition, 
and with jQuery Mobile on the horizon, jQTouch has one of the more 
uncertain futures of the libraries looked at in this chapter. 

Getting Started with jQTouch 

At the time of writing, the current stable release of jQTouch that is available for 
downioad from the jQTouch web site is version 1 , beta 2. Due to some changes that are 
going to be coming in a future release of the library, however, it is recommended that a 
more recent release be obtained from GitHub. The latest source snapshot can be 
downioaded from the following URL: 

https://github.com/senchalabs/jOTouch/zipball/fnaster 

NOTE: If you encounter any problems using the latest version of jQTouch from GitHub, then it is ^ 

probably worth checking the jQTouch web site to see if a new release has been published since I 

the publication of this book. Alternatively, the version of jQTouch files used in the samples are I 

available through the Apress source code repository for the book (atwww.apress.com), so you I 

can aiways take a look there also. I 

Once you have a copy of the jQTouch files, you shouid have a folder structure similar to 
the one displayed in Figuře 11-7. 
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Figuře 1 1 -7. The folder structure for JQTouch contains the source code and some useful démos. 



Within the jQTouch files there are two main directories of interest. The first is jqtouch, 
which contains the core JavaScript and CSS files required when using jQTouch, and the 
second is tliemes directory, which contains CSS and image resources that are used to 
customize the look and feel of a jQTouch application. 

jQTouch also provides samples in its démos directory— these are weil worth a look if you 
are interested in seeing what jQTouch can do. 

For our Moundz jQTouch app, we will need to copy both the jqtouch and themes 
directories into our jQTouch challenge directory. Figuře 11-8 shows how the structure 
of that folder shouid look after copying the files. 



272 



CHAPTER 11: Mobile Ul Frameworks Compared 




▼ DEVICES 

mtdia 

dewelopíTient 

▼ SHARED 
{■j files 
|B| blosscm 
iP fil» <AFP) 
|H| filřs (CIFS] 

▼ PLAC ES 

i3 Desktop 
^ dámo 

Applicatians 

i "I downloads 
I I projects 

I I pro-flndroid-web-apps 

1 I Drop box 

SE ARCH FOR 
^ Todav" 

Past Weelí 

Al\ ImagE! 
^ All Movies 
Qt^AW Docurrents 



_o_l |©'| 1^ 



^ Q base 


YřSttrdďVi 4-04 PM 




^ ^ in 






T jQTDUCh 


TodaVi 2 20 PM 










1*" indEx.htmI 


Yesterday, 4:20 PM 


4 KB 


▼ inf'd^.iirh 


LI. / l-íf L\J LXJ LJL.J± r iVI 






ii/iw^nioií^íi pjw 

L±f±Lií\íL\J L C J L rvfi 


12 KB 


Jl^ LUULII.J ^ 


L±/ ±LI £.Ki L\I L£..J± r lvi 


37 KB 






168 KB 


jjgj jQLJcry~l minjs 


27/07/2010 L2 S3 PM 


74 KB 


^ jC|Ufiry-1.4.Z.niin.js 


14/06/2010 11:48 AM 


74 KB 


^ mourtdz.css 


Todav, 11 16 AM 


4 KB 


Hl^ moundz.js 


Todav, 10:19 AM 


12 KB 


^ phonegapjs 


02/11/2010 9:55 AM 


90 KB 


▼ A themes 


04/10/2010 1:13 PM 






11/11/ZOlO Í2:31 PM 




^ default 


11/11/2010 12:31 PM 




^ Qjqt 


11/11/2010 12:31 PM 




► jQuervMobile 


Yesterday. 4:04 PM 




>■ ^ sencha 


Yesterday, 4:04 PM 





20 item!;. 41.18 GB avallable 



Figuře 11-8. Copy the jqtouch and themes folders from the jQTouch distribution into the Moundz challenge 
foíder. 



There are oniy a few modifications we need to make to our code to make it usable for 
jQTouch. 

<!DOCTYPE html> 

<html> 

<head> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 
<link rel="stylesheet" media="screen" href=" jqtouch/jqtouch.css" /> 
<link rel="stylesheet" media="screen" href="theines/default/theme.css" /> 

<link rel="stylesheet" media="screen" href="moundz.css" /> 
<script type="text/javascript" src=" jquery-l.4.2.min. js"></script> 
<script type="text/javascript" src=" jqtouch/ jqtouch. js"></script> 

<script type="text/javascript" src="moundz. js"></script> 

<!-- <script type="text/javascript" src="phonegap. js"></script> --> 

<script type="text/javascript" src="http://api.geominer.net/jsapi/vl/geominer . js"> 

</script> 

<script type="text/javascript" src="http: //maps. google. com/maps/api/js?sensor=true"> 
</script> 

<script type="text/javascript"> 
function initializeO { 

MOUNDZ. init(); 
} // initialize 
</script> 
</head> 

<body onload="initialize()"> 



</body> 
</html> 

Essentially, to get jQTouch in a position where it is ready to be used, we need to include 
jqtouch. js, jqtouch.css, and an appropriate theme file. In this particular oase, we're 
using the default theme, but both apple and jqt are also available. 

In the next section, we will need to make changes to our HTML, CSS, and JavaScript 
files SO that the application will behave as it should. 

Applying Some jQTouch-Ups to Moundz 

Now that we have jQTouch available to us in the Moundz application, leťs go about 
making the changes to have it display effectively. First, leťs start with the changes 
required in the HTML. Here we will change the code for the layout of the HTML body to 
the following: 

<body onload="initialize()"> 
<div id="jqt"> 

<div id="mapper"> 

<div class="toolbar"> 

<hl>Moundz</hl> 
</div> 

<div id="map_canvas" style="width:lOO%; height: lOO%;"></div> 
<div id="marker-nav"> 

<img src="img/navigation-arrow.png" class="left disabled" /> 

<span class='marker-title'>Test Text</span> 

<mg src="img/navigation-arrow.png" class="right" /> 
</div> 
</div> 

<div id="marker-detail"> 
<div class="toolbar"> 

<a href="#mapper" class="back">Back</a> 

<hl>Test Location</hl> 
</div> 

<div class='content'> 

</div> 
</div> 
</div> 
</body> 

In the preceding code, we make some relatively major changes to the HTML to structure 
things appropriately for jQTouch. jQTouch requires that a top-level #jqt div element be 
the Container for the jQTouch components of your application. CSS rules are crafted 
around this principle, and without it your application won't display as it should. This is 
one of the primary differences between the older release that is available on the jQTouch 
web site and the new version— the older version does not have the #jqt container 
requirement, and, while it makes things simpler, it also makes it more difficult to include 
non-jQTouch parts of your application. 




In our case, we made the following changes: 

1. We replaced our top-level #app div with a top-level #jqt div. 

2. We created "page" divs within the #jqt div to house our application pages. We 
have one for the map (ftmapper) and one for the detail display (#marker-detail). 
This is somewhat similar to the layout we had prior to adding jQTouch. 

3. Next, we added div elements with the class of toolbar to the pages that we want 
a toolbar for (which is all of them). In the case of the #marker-detail page, we 
also added a Back button, as, when the detail view is displayed, we want to be 
able to return to the main map view. 

4. We moved our #marker-nav bar to within the #mapper div so that we can navigate 
around our markers. 

If you have applied the changes successfully, your jQTouch version of Moundz will 
simply display an empty page (due to CSS rules). We now need to activate jQTouch 
within the moundz. js file to get things displaying correctly. We will do this by modifying 
the initScreen function inside moundz. js. 

function initScreenO { 
jOT = new $.jOTouch(); 

$( '#map_canvas ' ) .height( 
$( '#mapper' ) .height() - 
$('#mapper .toolbar ') .outerHeight() - 
$( '#marker-nav' ) .outerHeight() 

); 

} // initScreen 

In addition to activating jQTouch, we set the height of the map canvas to fill the available 
space in the #mapper div. Qnce this is done, you shouid see a screen similar to the one 
displayed in Figuře 11-9. 




With those modifications made, all of the basic elements are there. However, we have a 
rather unappealing marker navigation bar displayed. Leťs make some modifications to 
tine moundz . css file to improve the look and feel of the marker navigation bar. Locate the 
rule for the #marl<er-nav element and strip it back to a very basic look and feel: 

#marker-nav { 

/* set generál color and style */ 
color: whitej 
font-weight: bold; 
text-align: center; 
padding: lOpx; 

} 

With that simple modification, we shouid have a more appealing display. Figuře 11-10 
shows an example of what you shouid expect to see. 
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Figuře 11-10. With some CSS simplification, the display looks much improved. 

As we have kept our structure from the originál application with regard to the #marl<er- 
nav bar, the application code all works as it did before. Clicking the left and right arrows 
will toggie between resources and the title updates, as it should. All that remains now is 
to update the functionality within the MOUNDZ module to properly handle showing the 
resource details when the resource title is clicked. 

Because we have kept many of the Ul elements the same for the jQTouch sample, the 
changes required here are very simple. All we need to do is update the code in our 
showScreen function to call the correct method in jQTouch to update the screen: 

function showScreen(screenld) { 

jOT.goTo('#' + screenidj 'slide')j 
} // showScreen 

Essentially, we remove all of our custom code and pass the request on to the goTo 
method of our jQTouch object. This takés care of the screen navigation, but we also 
need to very slightly tweak the activateMarker function to update the title of the detail 
page: 

function activateMarker(marker) { 

// iterate through the markers and set to the inactive image 
for (var ii = 0; ii < markers. length; ii++) { 

markers [ii] . setIcon( ' img/pin-inactive.png' ); 
} // for 

// update the specified marker's icon to the active image 
marker.setIcon( ' img/pin-active.png' ); 



// update the navbar title using jOuery 



$( '#marker-nav .marker-title' ) 
. html (marker . getTitle( ) ) 
.removeClassC has-detail' ) 
.unbindC click' ); 



$ (' #mar ker- detail hl '). html (marker . getTitle () ) j 



} 



// if content has been provided, then add the has-detail 

// class to adjust the display to be "link-like" and 

// attach the click event handler 

var content = fnarkerContent[marker.getTitle()] j 

if (content) { 

$( '#marker-nav .marker-title') 
.addClass( ' has-detail' ) 
.click(function() { 

$( '#marker-detail .content' ) .html(content); 
showScreen( 'marker-detail' ); 

}); 

} // if 

// update the marker navigation controls 
updateMarkerNav(getMarkerIndex(marker)); 
// activateMarker 



Once we have done this, we have successfully integrated jQTouch into Moundz. Figuře 
11-11 shows the screen you shouid see once you are able to navigate from a marker to 
the detail page. 
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Figuře 1 1 -1 1 . We are now able to navigate to the details for a resource in our jQToucli Moundz app. 
This concludes our sample integrating with jQTouch. Next up is jQuery Mobile. 



jQuery Mobile 

While third on our list of mobile frameworks, jQuery IVlobile is one of the frameworks that 
has probably attracted the most attention. This is due in part to the popularity of the 
jQuery library, and also in part to the amount of planning that has gone into the library. 

■ Framewor/f: jQuery IVlobile 

■ Style: Markup based 

■ Web s/ře: http://jquerymobile.coni 

■ License: Open source (MIT or GPL) 

■ Source code: https://github.com/jquery/jquery-mobile 

■ Requirements: jQuery (1 .4.4) 

The following are some of jQuery Mobile's strengths: 

■ A great deal of research went into the statě of mobile device browsers 
before any work commenced on the library. An excellent resource 
created as part of this research is the Mobile Graded Browser Support 
chart, available at http://jquerymobile.com/gbs. 

■ There are sponsors and a very strong team behind this library. 

■ jQuery Mobile is based on and weil integrated with jQuery. 

■ jQuery Mobile provides great documentation. 

■ Iťs likely to be considered a quality solution by tech-savvy clients 
when building mobile applications, given that it is an official jQuery 
Foundation product. Thus, there's little need to justify its use when 
building a mobile web application. 

The following are some of its weaknesses: 

■ At the time of writing, iťs still oniy in an alpha release statě. 

■ For some, the tight integration with jQuery will be considered a 
weakness. 

^^NOTE: While the Mobile Graded Browser Support data was primarily developed as a tool to ass^^^ 
^ with the development of the jQuery Mobile library, this is an excellent resource when building J 
mobile web applications in generál. This chart is invaluable for making quick determinations of 
where particular mobile applications may or may not run. Theoretically, the code that we have 
j worked on throughout the course of the book shouid work on any WebKit-powered device that is 1 
rated with A-class support. 



Getting Started with jQuery Mobile 



At the time of writing, jQuery Mobile is in its 1 .0 alpína 2 release. WInile there are likely to 
be some changes between tinis version and tine eventual stable release of 1.0, tinings 
shouid work in more or less the same way. As sucin, iťs probably best to downioad the 
latest stable release, which can be obtained from littp://jquerymobile.com/download. 

While that page includes information on how to include jQuery from a CDN (content 
delivery network— see http://en.wikipedia.org/wiki/Content_delivery_networl< for 
more information), it is recommended that you downioad the ZIP file so that wrapping 
the application with PhoneGap is still an option. 



NOTE: While a CDN offers an efficient way for web sites to optimize load times for scripts by 
making use of a distributed network of servers, this does prevent applications from being 
wrapped effectively for offline distribution. Carefully consider the type of application distribution 
before using a CDN in mobile web application code. 




Once you have downloaded the jQuery Mobile distribution, you shouid have a set of files 
similar to that shown in Figuře 11-12. 
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Figuře 11-12. Currently, the jQuery Mobile distribution is very simple and light. 




While the distribution does not contain any samples, these can be viewed online. For 
instance, tine 1 .0 alpina 2 démos are available at http://jquerymobile.eom/demos/l.0a2. 

In addition to tine jQuery Mobile library files, we will also need to obtain jQuery 1 .4.4, as 
tinis is a prerequisite for tlie jQuery Mobile framework. One of the simplest ways to get 
jQuery 1 .4.4 is to downioad it from the CDN location, at 
http://code.jquery.eom/jquery-l.4.4.min.js. 

Now that we have the files that we need, leťs copy them into our jQuery Mobile Moundz 
project. From the jQuery Mobile distribution, copy all the files into the main Moundz 
directory, and copy the jquery-l.4.4.min. js file there also. After you have done this, 
the Moundz application directory shouid resemble Figuře 11-13. 
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Figuře 11-13. Moundz application folder structure after adding required jQuery Mobile files 



Once we have added the required jQuery Mobile (and jQuery) files, there will be a little 
duplication. If we were building a production application, we wouid probably clean that 
up, but for the sake of our challenge we'll let it slide. We'll now make the required 
modifications to the HTML: 

<!DOCTYPE html> 

<html> 

<head> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 
<link rel="stylesheet" media="screen" href="jquery.mobile-l.0a2.min.css" /> 



</-- <link rel="stylesheet" media=" scxeen" hief="moundz.css" /> --> 
<script type="text/javascript" src=" jquery-l.4.4.itiin. js"></script> 
<script type="text/javascript" src="jquery. mobile- l.0a2. min. js"></script> 

<script type="text/javascript" src="moundz. js"></script> 

<!-- <script type="text/javascript" src="phonegap. js"></script> --> 

<script type="text/javascript" src="http: //api.geominer.net/jsapi/vl/geominer. js"> 

</script> 

<script type="text/javascript" src= "http ://maps. google. com/maps/api/js?sensor=true"> 
</script> 

<script type="text/javascript"> 
function initialize() { 

MOUNDZ.initO; 
} // initialize 

</script> 
</head> 

<body onload="initialize()"> 

</body> 
</html> 

In the preceding code, we added the required jQuery Mobile files to the index.html file 
and also changed the version of jQuery that is included in tlie sample (from jOuery- 
l.4.2.min. js to j0uery-l.4.4.min. js). Additionally, we commented out tlie moundz.css 

file to prevent any CSS conflicts. 

We are now ready to get lVioundz working with jQuery IVIobile. 



Moundz and jQuery Mobile 

Lil<e jQTouch, jQuery IVIobile uses a markup-based approach to a Ul framework. This 
means that we need to construct our HTML so that jQuery Mobile can interpret it 
correctly and apply necessary styling and JavaScript processing. A good starting point 
for our jQuery Mobile Moundz application's index, html file follows. 

<IDOCTYPE html> 

<html> 

<head> 

</head> 

<body onload="initialize()"> 
<div id="[nain" data-role="page"> 

<div data-role="header"> 
<hl>Moundz</hl> 

</div> 

<div id="map_canvas" data-role="content"></div> 

<div data-role="footer" class="ui-bar" data-id="moundz_footer"> 

<div id="marker-nav" data-role="controlgroup" data-type="horizontal"> 

<a href="#" data-role="button" data-icon="arrow-l" class="left">Previous</a> 
<a href="#marker-detail" data-role="button">** Pláce Name **</a> 
<a href="#" data-role="button" data-icon="arrow-r" class="right">Next</a> 
</div> 
</div> 
</div> 

<div id="marker-detail" data-role="page"> 
<div data-role="header"> 



<hl>Location Detail</hl> 
</div> 

<div data-role='contenť> 

</div> 
</div> 
</body> 
</html> 

In the preceding code, we created two separate pages for our application display. First, 
we have our main application page, winicin will contain tine nnap, and, second, we Inave 
tine page tínat will display the detail from the selected location (as per our non-framework 
version). 

In jQuery Mobile, the data-role attribute in an HTIVIL element is used to provide jQuery 
Mobile with information regarding its purpose. Our pages have a data role of page, and 
inside each page we have more divs with different values for the data-role attribute. 
jQuery Mobile makes extensive use of data-* attributes to specify how Ul elements 
shouid behave; while not exhaustive. Table 11-1 lists a few that we will encounter in this 
sample. 



Table 11-1. Some of the Common jQuery Mobile Data Attributes 


Attribute 


Descríption 


data- 


■role 


The value of the data-role attribute defines the type of Ul element that 
will be created once the HTML has been processed by jQuery Mobile. 
Primarily, Ul elements are transformed by the jQuery Mobile library at 
runtime by simply adding relevant CSS classes which influence the 
look and feel of the originál HTML. In some cases, jQuery Mobile will 
also add additional HTML elements to the DOM to create the relevant 
mobile web page. 


data- 


■id 


The data-id element is used to specify a unique identifier for the Ul 
control. This ID can be used to tell jQuery Mobile that a particular 
element shouid remain consistent between different pages in the Ul. 


data- 


■icon 


Some Ul elements (such as the button control) can contain icons to 
help represent the purpose of the control. Icons are specified using a 
name that relates to a particular icon. There are a number of built-in 
icons that can be used, such as the one in our sample. Additionally, 
you can use custom icons by specifying a unique identifier and then 
defining some custom CSS for that icon. More information can be 
found at the following URL: 

http://jquerymobile.com/demos/l.0a2/#docs/buttons/buttons- 
icons.html 



With our modified HTML with the data-role attributes in pláce, jQuery Mobile can begin 
to work with our application layout. Figuře 11-14 shows an example of the Ul generated 
from the preceding index.html file. 




Figuře 11-14. The initial effort with jQuery Mobile yields a header and footer, but not much of a map. 

As with our work with the other frameworl<s so far, the default instructions for including a 
Google map don't yield a very positive result. As such, some speciál treatment is going 
to be required to display the map correctly. 

NOTE: When writing this book, we got to framework three and the integratlon of a Google map 
still consistently failed, so it was time to do some further investigation. Was it just one version of 
Android that had this issue? It wouid appear not — testing with Android 1 .6, 2.1 , and 2.2 all 
revealed the same problém across the board. 

While not conclusive, this seems tied to the fact that each of the frameworks makes use of 
absolute positioning to some degree with regard to controlling their layouts. This in turn makes 
correctly sizing child div elements difficult, and yields an incorrect map display. Iťs something 
that can be worked around, but it is nonetheless frustrating. 

As with our work with jQTouch, the fix is to manually size the map container to fit the 
containing page. We will make our adjustments to moundz. js to do that, and perform 
some other initialization to prepare the Moundz Ul. As with earlier examples, we make 
our adjustments to the screen layout in the initScreen function: 

function initScreenO { 

// size the canvas to the height of the page minus the header 
$( '#map_canvas ' ) .height( 
$('#main'). height O - 

$('#main div[data-role="header"] ' ).outerHeight() - 
$('#main div[data-role="footer"] ' ).outerHeight() - 30 
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} // initScreen 

In this case, the changes required are relatively minor, but hardly scientific. We 
essentially size the height of the map to the height of the page (the #main div) minus the 
height of the header and footer within the page (plus a fudge factor of 30 pixels to have 
everything display accurately). With that change complete, our Moundz main screen is 
starting to look the part. Figuře 11-15 shows an example. 
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Figuře 11-15. The JQuery Mobile Moundz interface is starting to come togetlier. 



With the interface starting to come together, we just need to make some further 
modifications to moundz. js to get things working with our modified HTML. 

First, we will update the activateMarker function to update the middle button on the 
page footer: 

function activateMarker(marker) { 

// iterate through the markers and set to the inactive image 
for (var ii = 0; ii < markers. length; ii++) { 

markers [ii] . setIcon( ' img/pin-inactive.png' ); 
} II for 

// update the specified marker's icon to the active image 
marker.setIcon( ' img/pin-active.png' ); 



// update the navbar title using jOuery 
$ (' #mar ker- na v a [ href = "#marker- detail " ] ' ) 

.unbind('tap') 

.find('.ui-btn-texť) 

. html (mar ker . getTitle () ) ; 



// if content has been provided, then add the has-detail 

// class to adjust the display to be "link-like" and 

// attach the click event handler 

var content = markerContent[marker .getTitle() ] ; 

if (content) { 

$ ( ' ttmarker- na v a [ href = "#mar ker- detail " ] ' ) 
.tap(function() { 

$('#marker-detail div[data-role="content"] ' ).html(content); 



// update the marker navigation controls 
updateMarkerNav(getMarkerIndex(tnarker) ) ; 
} // activateMarker 

While the start of the code here is exactly the same as we had in the non-framework 
version, there are some differences after that: 

1. Rather than target the anchor using a class selector, we are now using an 
attribute selector to find the link that takés us to the #marker-detail page. 

2. Once that link is found, we unbind from the tap event rather than the click event, 
as jQuery Mobile uses these tap events to communicate that the user has tapped 
a particular control on the screen. 

3. Next, we locate a span with the ui-btn-text class within the anchor tag and 
replace its content with the title of the marker. As mentioned previously, for some 
of the data-role types, jQuery Mobile will generate additional HTML elements to 
properly create the look and feel needed for the Ul. This is the oase with buttons. 
As such, we need to update the text within the ui-btn-text span within the 
anchor rather than the text of the anchor itself. 

4. We then move on to binding to the tap event of the button when a marker has 
content. As before, we locate the link that will take us to the #marker-detail page 
and add a handler to the tap event that will occur. The handler for this tap event 
simply updates the HTML content in the content area of the #marker-detail page, 
in a similar way to what our non-framework Ul did previously. 

Once these changes have been made, you shouid be able to navigate to a detail screen 
in the application by clicking the middle button in the footer. Figuře 11-16 shows how 
the two pages shouid look in an Android emulátor. 
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Figuře 11-16. We now have the basis of a working multipage jQuery Mobile application. 



Now that we have simple paging working in the application, we just need to attach 
appropriate event handlers to allow our user to navigate between all the resource 
locations that are displayed. We do this by making some fairiy subtie changes to the 
updatel^arkerNav function: 

function updateMarkerNav(markerlndex) { 
// flnd the marker nav element 
var markerNav = $( '#marker-nav' ); 

// reset the disabled statě tor the images and unbind click events 
markerNav.f ind( 'a ' ) 

.addClass( ' disabled ' ) 

.unbind('tap' ); 

// if we have more markers at the end of the array, then update 
// the marker statě 

if (markerindex < markers. length - l) { 
markerNav. find( 'a. righť ) 
.removeClass( ' disabled ' ) 
.tap(f unctionO { 

activateMarker(markers[markerIndex + l]); 

}); 

} // if 

if (markerindex > O) { 

markerNav.f ind( 'a. left ' ) 

.removeClass( 'disabled' ) 
.tap(f unctionO { 

activateMarker(markers[markerIndex - l]); 



}); 

} // if 
} // updateMarkerNav 

Here, we're essentially just replacing our search for img tags within the #marker-nav div 
with a search for anchor elements instead. Additionally, as before, we replace references 
to click events with appropriate tap handlers. 

Thaťs it. Our Moundz application as it existed before has been converted to a jQuery 
Mobile application with relative ease. 

Sencha Touch 

Sencha Touch is the last of the frameworks that we will look at in this chapter with our 
Moundz conversion challenge. In some respects, Sencha Touch couid be considered 
the next evolution of jQTouch, considering that jQTouch's creator (David Kaneda) joined 
Sencha and became part of the teann that eventually released Sencha Touch. Like Jo, 
Sencha Touch follows a declarative style. 

■ Framework: Sencha Touch 

■ Style: Declarative 

■ Web s/ře: www. sencha.com/products/touch 

■ License: Dual-licensed (GPL and connmercial— currently free) 

■ Source coc/e: Available in downioad 

■ Requirements : N o n e 

The following are some of Sencha Touch's strengths: 

■ Sencha Touch has an extremely robust and weil-tested framework, so, 
when building a mobile web Ul for Android, it will also work weil on 
iOS devices. 

■ The framework also has user interface elements that cater for larger 
mobile device screen sizes (such as tablet devices).. 

■ It has excellent touch event support, so iťs a great choice for building 
touch- and canvas-oriented applications. 

■ It has the most complete suitě of Ul widgets of any of the frameworks 
covered in this chapter. 

■ It has very solid documentation. 
The following are some of its weaknesses: 

■ Sencha Touch is the most heavyweight of the frameworks we've 
looked at (by quite a bit). Its large library slze is mitigated by the ability 
to customize the build of the library, but it is inconvenient. 



■ There is some uncertainty about its commercial licensing. Iťs free for 
open source projects, but the commercial license applies for closed- 
source projects. Currently, the library is provided at no cliarge, but this 
couid aiways change. 



Getting Started with Sencha Touch 



As with the other frameworks we have worked with so far, we first need to downioad 
Sencha Touch. As Sencha Touch is the oniy framework in this chapter that is covered by 
a commercial license (when used for commercial development), you will need to register 
your details before downioading. You can, however, downioad the GPL version if you 
intend to release an application built with Sencha Touch under a GPL license. 

Either way, head to the Sencha Touch product page and follow the instructions to 
downioad the library. Once you have the library, extract the archive, and you shouid see 
a folder structure similar to what is displayed in Figuře 11-17. 
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Figuře 11-17. The Sencha Touch 1.0 release folder structure 



The Sencha Touch distribution contains quite a large number of files, including the 
source files for the library and some pretty useful tools for working with the library. We 



Cl 



won't go into detail on these here, but if you have the time they are definitely worth 
investigating. 

For the purposes of the challenge, leťs take the files that we need and copy thenn into 
the IVloundz challenge directory. For this exercise, we will tal<;e the JavaScript files fronn 
the main directory, and the css directory from the resources folder. Once we have done 
this, the Sencha Moundz directory shouid lool<; something lil<e Figuře 11-18. 
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Figuře 11-18. Aňer adding the required Sencha Touch files to the Moundz directory, we will have a css directory 
and a few extra JavaScript files. 



With the required files in places, leťs now modify our HTML to include the required files. 
As with our earlier example with Jo, we will remove the HTML elements from the body 
tag, as Sencha uses a declarative style to create the required HTML elements. 

<!DOCTYPE html> 

<html> 

<head> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 

<link rel="stylesheet" media="screen" href="css/android.css" /> 

<!-- <link rel="stylesheet" media="screen" hief="moundz.css" /> --> 

<script type="text/javascript" src=" jquery-l.4.2.min. js"></script> 

<script type="text/javascript" src="sencha-touch-debug. js"></script> 

<script type="text/javascript" src="moundz. js"></script> 

<!-- <script type="text/javascript" src="phonegap. js"></script> --> 

<script type="text/]avascript" src="iittp: //api. geominer.net/ jsapi/vl/geominer.js"> 




</script> 

<script type="text/javascript" src= " http : //maps. google. com/maps/api/js?sensor=true"> 
</script> 

<script type="text/javascript"> 
function initializeO { 

// MOUNDZAnitO; 
} // initialize 
</script> 
</head> 

<body onload="initialize()"> 

</body> 

</html> 

In the preceding code, we included the android.css stylesheet, which is part of the 
Sencha Touch distribution, and commented out moundz.css to prevent any CSS 
conflicts. We then included the sencha-touch-debug. js file so we can work through any 
problems that might arise during the integration effort (this file wouid be replaced with 
sencha -touch. js before being released). Finally, we commented out the call to 
MOUNDZ.initO from the initialize function. We did this because Sencha Touch has its 
own "ready" event that we will need to hook into to properly initialize the application. 

Moundz and Sencha Touch 

By now, you shouid be feeling pretty comfortable integrating frameworks into Moundz. 
Integrating Sencha will be a little different from our previous experiences due to the way 
Sencha libraries function. 

The first part of this process is to call Ext.setup within our MOUNDZ module to properly 
initialize our Sencha Touch application: 

MOUNDZ = (functionO { 

Ext.setup({ 

onReady: function() { 
module, init O; 

} 

}); 

return modulej 

})(); 

In this case, we are simply telling Sencha Touch that, when it is properly initialized, we 
want to execute the init function of our MOUNDZ module. In addition to the onReady 
handler defined in the preceding code, the Ext.setup function can take parameters that 
can be used to configure the look and feel of the application and device integration for 
various platforms. More details on the setup function can be found in the Sencha Touch 
documentation, at http : //dev. sencha . com/deploy/touch/docs/?class=Ext. 

From this point, we then proceed to update our initScreen function to create the main 
Ext. Panel that will be used to drive our application. 

MOUNDZ = (functionO { 

// initialize variables 



var mainPanel = null, 
posWatchld = 0; 



function initScreenO { 

mainPanel = new Ext.Panel({ 
id: 'mainPanel', 
layout: 'carď, 
dockeditems: [ 

createHeader()^ 
createFooterO 

fullscreen: true, 
ui: 'lighť, 
defaults: { 

scroll: falše 

}. 

items: [{ 

xtype: 'map', 
id: 'main_map' 

}, { 

xtype: 'sheeť, 

id: 'details_panel' , 

style: 'color: white' 

} 

], 

llsteners: { 

cardswltch: function(container, newCard, oldCard, index, animated) { 
var backButton = Ext.getCmp( 'goback' ); 
if (backButton) { 

backButton [index === O ? 'disable' : 
' enable ' ] . apply (backButton) ; 

} // if 

} 

} 

}); 

} // initScreen 
var module = { 

}; 

Ext.setup({ 

onReady: function() { 
module. init(); 

} 

}); 

return module; 

})(); 

In this code, we update the initScreen function to create the main panel for the 
application. We are creating an Ext. Panel that will be used to hold the two pages for our 
application. The first of these pages is the map control, and the second is a details panel 




that we will show the resource information on— you can see the pages defined in the 
items array of the panel definition. 

At this point, it is worth noting that Sencha Touch actually provides a map control for 
embedding a Google map into our Ul. This is definitely going to come in handy, as the 
map integration has been problematic in most of the previous frameworks. 

Additionally, note the two function calis that are embedded within the dockeditems array. 
This is where we will create our top and bottom toolbars for our application layout. 

Leťs now take a look at the createHeader function that is used to create the application 
header: 

function createHeaderO { 
return new Ext.Toolbar({ 
dock: 'top'j 
ui: 'lighťj 
defaults: { 

iconMask: true 

}, 

layout: { 

pack: 'justify' 

}, 

items : [{ 

xtype: 'button', 
text: 'Back', 
ui: 'back', 
id: 'goback', 
disabled: true, 

handler: f unction(button, event) { 

Ext .getCmp( 'mainPanel ' ) .setCard(o); 

} 

}, { 

xtype: 'spacer' 

}, { 

xtype: 'panel', 

html: ' <hl>Moundz</hl> ' 

}, { 

xtype: 'spacer' 

}] 

}); 

} // createHeader 

You can probably see in this code that the process of creating a header in Sencha is not 
as easy as in some other frameworks. The payoff is some extra robustness when it 
comes to rendering the display, but for some people the cost is too high. Additionally, 
the learning curve with Sencha is probably a little steeper than with other frameworks, 
purely due to the amount of functionality it offers. 



NOTE: Due to the complexity of the Sencha Touch framework, we won't be able to explain all of 
the components in detail. We will, however, endeavor to provide a feel tor liow the frameworl< 
operates and put you on thie patli to finding out more and being able to explore the framework on 



One of the most important things to be aware of is the use of xtype to define Ul elements. This 
is similar in many respects to the way jQuery Mobile uses the data -role attribute in the HTML 
to specify the kind of Ul element that shouid be created. 



UNDERSTANDING OBJECT INITIALIZATION IN SENCHA TOUCH 



The main thing to get your head around when using the xtype attribute (as we did in the previous code 
sample) is that it is essentially interchangeable with manually creating its relevant class and referencing 
that variable. This is one of the quite clever aspects of the Sencha Touch approach, and it does create 
some interesting possibilities. 

While it may take a while to digest and understand, there is a very fluid mapping between the object 
definitions using object literals and xtypes and their more formal definitions. For an example, take a 
moment to review the Ext . Toolbar reference at the following URL: 

http ://dev. sencha. com/deploy/touch/docs/?class=Ext.Toolbar 

You shouid start to see the relationship between the preceding definition and the attributes in the 
Ext . Toolbar class. Try another one — this time Ext . Button: 

http : //dev. sencha . com/deploy/touch/docs/?class=Ext . Button 

Notice that, if we were to create a new Ext . Button object, it wouid accept a number of configuration 
options, and this wouId include items such as text and disabled. These are defined in the preceding 
object literal definition. 

To demonstrate the point, leťs quickly refactor the createHeader function to first define an 
Ext. Button class and then include the object in our definition of the Ext. Toolbar: 

function createHeaderO { 

var backButton = new Ext.Button({ 
text: 'Back', 
ui: 'back', 
id: 'goback', 
disabled: true, 

handler: f unction(button, event) { 

Ext . getCmpC mainPanel ' ) . setCard(o) ; 

} 

}); 

return new Ext.Toolbar({ 
dock: 'top', 
ui: 'lighť, 
defaults: { 

iconMask: true 

}, 
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ayout: { 

pack: 'justify' 

items : [backButtorij { 

xtype: 'spacer' 
, { 

xtype: 'panel', 
html: ' <hl>Moundz</hl> ' 
, { 

xtype: 'spacer' 

] 

}); 

} // createHeader 

What we have done in this code is equivalent to the earlier code. Hopefully, this gives a bit of insiglit as to 
the different ways in whicli Ul elements can be defined in Sencha Touch. 



Witin tlie createHeader function complete, we now just need to implement tlie 
createFooter function to finish off the basic layout of our application. 

function createFooter O { 
return new Ext.Toolbar({ 
dock: 'bottom', 
ui: 'lighť, 
layout: { 

pack: 'justify' 

}. 

items: [{ 

xtype: 'button', 

text: 'Previous', 

handler: f unction(button, evt) { 

activateMarker(markers[markerIndex - l]); 

} 

}, { 

xtype: 'button', 
id: 'btnResource', 
text: 'Resource Title', 
handler: f unction(buttonj evt) { 
mainPanel . setActiveltem(l) ; 

} 

}, { 

xtype: 'button', 
text: 'Nexť, 

handler: f unction(button, evt) { 

activateMarker(markers[markerIndex + l]); 

} 

}] 

}); 

} // createFooter 

In this code, we create another Ext.Toolbar that is set to dock at the bottom of the 
screen. For the toolbar items, we specify three buttons, one each for moving forward 
and back, and another to take us to the resource details page. 



Each of the buttons is assigned appropriate event handlers, the Next and Previous 
buttons activate the appropriate markers in tine nnarl<;er list, and tine button that will 
display the resource title takés the user to the details screen when it is clicked. 



All being weil, a screen similarto the one in Figuře 11-19 shouid be displayed. 
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Figuře 11-19. The initial display of our Ul in Senclia Touch actually displays a map — impressive. 



As you can see, we have an application laid out with a mapping control appropriately 
sized to the screen. So, while we had to do some extra work to get the Ul set up, the 
inclusion of the mapping control into Sencha Touch has made life easy here. We now 
need to move on to initializing the map with the appropriate location and get some 
markers displayed on the map. 

To have the map display integrate with our existing Moundz application code, we need 
to make some modifications to the gotoPosition function. 

function gotoPosition(position, zoomLevel) { 
// define the required options 
var myOptions = { 

zoom: zoomLevel ? zoomLevel : DEFAULTZOOM, 

center: positiorij 

mapTypeControl: falše, 

streetViewControl: falše, 

mapTypeId : google . maps . MapTypeId . ROADMAP 

}; 
/* 

// initialize the map 

map = neu google. maps. Map( 

document.getElementById("map_canvas"), 



myOptions); 

*/ 

II save a reference to the map control 
map = Ext.getCmp( 'main_map' ) .map; 

// set the options of the map 
map. setOptions (myOptions); 

} // gotoPosition 

In the preceding code, we do three things: 

1. We comment out the previous code that created a Google map control for us; this 
Is no longer required, since Sencha Touch has created one for us. 

2. We get a reference to the map that Sencha Touch has created, and we save that 
to the map variable that is part of the MOUNDZ module. As we use this variable in 
other function calis, our existing functionality shouid just work. 

3. We update the options of the map to match the options we wouid have provided 
if we had created the map ourselves. 

Once this is done, you shouid get a display similar to the one shown in Figuře 11-20. 
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Figuře 11-20. Our Sencha Touch version of Moundz now displays markers. 

We now just need to make some changes to functions within the MOUNDZ module to 
synchronize our application statě with the Ul controls. We will start with the 
activateMarker function: 



MOUNDZ = (functionO { 



// initialize constants 
var DEFAULT_ZOOM = 8, 

GEOMINER_MOUNDZ_URL = 'http://api.geominer.net/vl/moundz'; 

// initialize variables 
var geominer = nullj 

markerindex = Oj 

posWatchld = 0; 

/* priváte functions */ 

function activateMarker(marker) { 

// iterate through the markers and set to the inactive image 
for (var ii = 0; ii < markers. length; ii++) { 

markers [ii] . setIcon( ' img/pin-inactive.png' ); 
} // for 

// update the specified marker's icon to the active image 
marker.setIcon( ' img/pin-active.png' ); 

Ext.getCmp( ' btnResource' ) .setText(marker.getTitle()); 

Ext . getCmp ( ' details_panel ' ) . update (markerContent [ mar ker . getTitle () ] ) ; 

// update the marker navigation controls 
markerindex = getMarkerlndex(marker); 

} // activateMarker 

})();" 

Interestingly, the activateMarker function has actually been simplified using Sencha 
Touch here. We simply set the text of the middle button using the setText nnethod of the 
button, and call the update method of the details_panel to supply the appropriate 
content to the details page. 

Additionally, we assign the current mari^er index to the new module variable 
markerindex, which will allow the buttons that we defined in the createFooter function 
to switch between the various resource locations. 

Once this is done, we can navigate through the markers using the navigation buttons, 
and display the details for a resource by clicking the resource Information button in the 
footer. 

There we have it— a Sencha Touch version of our Moundz application, as shown in 
Figuře 11-21. 
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Figuře 11-21. The finál Sencha Touch version of our Moundz application 



Summary 

This brings us to the end of our look at four different mobile Ul frameworks. As we have 
seen, each of the four frameworks discussed in this chapter is quite different in its 
approach, and each has strengths and weaknesses in different areas. 

As mentioned, there really is no best framework. jQuery Mobile and Sencha Touch are 
definitely both going to be heavy hitters over the next couple of years, and iťs likely that 
fans of one framework will dislike the other due to the different approaches. Additionally, 
Jo is gaining popularity and jQTouch has a loyal community behind it (how it competes 
with jQuery Mobile in the long run, though, will be interesting). 

Hopefully, this chapter has assisted you in identifying a mobile Ul framework that sits 
weil with your own particular style. Or perhaps you'd prefer to construct your own 
application interface due to particular requirements that you have. 

For our sample game application, we will take the jQuery Mobile interface that we 
worked through and polish it up in the next chapter. We're using jQuery Mobile primarily 
because we have worked extensively with jQuery throughout the book. 



Chapter 



12 



Polishing and Packaging 
an App for Release 



One of the great things about developing mobile application using web technologies is 
that you have a choice about how you package and deploy your application. If you build 
with native tools, then you have oniy one option. Admittedly, iťs a very good option, but 
still you don't have a choice. 

By using web technologies coupled with tools lil<e PhoneGap, you can choose to deploy 
you application for consumption via a web browser, or wrap your web application for 
native marketplace distribution. 

In this chapter, we will finish writing our sample geosocial game app, Moundz, using the 
jQuery Mobile sample that we compiled in the previous chapter. Once coding is 
complete (we still have a bit to do), we will package that for marketplace distribution. 

Continuing on with jQuery Mobile 

In the last chapter, we looked at four different mobile Ul frameworks, one of which was 
jQuery Mobile. Given that throughout the book we have used jQuery extensively, it 
makes sense that we carry the jQuery Mobile sample forward to completion. 

NOTE: At the time of writing, jQuery Mobile is still in an alpha release status, so minor tweaks 
may be required to make the samples work on the latest stable version that is presently 
available. 



Reinstating the Login Screen 



When we first put together the Moundz application without using a mobile Ul framework, 
we included a splash and login screen for the application. We'll put that back in for our 
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jQuery Mobile version of the application. But first, leťs copy the jQuery Mobile cinallenge 
code from tine previous cinapter to a pláce winere we can finisin it off. Ratiner tínán 
overwriting our previous moundz directory, copy tine files from 

frameworl<s/challenge/jOueryMobile to a moundz- jqm directory. Once you have done 
tinis, you shouid have a directory structure that resembles Figuře 12-1 . 
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Figuře 12-1. Ihe directory structure for the jQuery Mobile version ofIVIoundz 



We will now go about making the required modifications to the code. Leťs start with the 
index.html file: 

<!DOCTYPE html> 

<html> 

<head> 

<title>jOueryMobile Moundz</title> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 

<linl< rel="stylesheet" media="screen" href="jquery.mobile-l.0a2.min.css" /> 

<link rel="stylesheet" media="screen" href="moundz.css" /> 

<script type="text/javascript" src=" jquery-l.4.4.inin. js"></script> 

<script type="text/javascript" src=" jquery .mobile-l.0a2.min. js"></script> 

<script type="text/javascript" src="moundz. js"></script> 

<!-- <script type="text/javascript" src="phonegap. js"></script> --> 

<script type="text/javascript" src= " http : //api. geominer.net/ jsapi/vl/geominer.js"> 

</script> 

<script type="text/javascript" src= " http : //maps. google. com/maps/api/js?sensor=true"> 



</script> 

<script type="text/javascript"> 
function initializeO { 

MOUNDZ.initO; 
} // initialize 
</script> 
</head> 

<body onload="initialize()"> 
<div id="splash"> 

<strong>Welcome to</strong> 

<img src="img/moundz_logo.png" /> 

<p class="hint"> 

Press the 'Sign in with Twitter' button below to get started playing. 

</p> 

<span id="login"></login> 
</div> 

<div id="main" class="noauth" data-role="page"> 
<div data-role="header"> 

<hl>Moundz</hl> 
</div> 

<div id="map_canvas" data-role="content"></div> 

<div data-role="footer" class="ui-bar" data-id="moundz_footer"> 

<div id="marker-nav" data-role="controlgroup" data-type="horizontal"> 

<a href="#" data-role="button" data-icon="arrow-l" class="left">Previous</a> 
<a href="#rtiarker-detail" data-role="button">** Pláce Name **</a> 
<a href="#" data-role="button" data-icon="arrow-r" class="right">l\lext</a> 
</div> 
</div> 
</div> 

<div id="marker-detail" class="noauth" data-role="page"> 
<div data-role="header"> 

<hl>Location Detail</hl> 
</div> 

<div data-role='contenť> 

</div> 
</div> 
</body> 
</html> 

In the preceding code, we make oniy a few changes, and these mainiy involve 
reinstating code that we had earlier. 

First, we once again include the moundz.css stylesheet, as it includes styles that are 
needed to properly style the splash screen. Next, we reinstate the #splash div to have 
the splash screen properly displayed, and finally we add the class noauth to both of the 
jQuery Mobile pages that we created in the previous chapter. 

We now need to make some changes to moundz.css to bring the old and the new 
together nicely. The first change that is required to the CSS file is updating the rule that 
previously specified the style for the #app div with the following: 

/* application window styles */ 

div. noauth { 

visibility: hiddenj 

} 




Very simply, this means that any div elements with the class of noauth will not be 
displayed at application start. The next step in tweaking the moundz.css file involves 
completely removing any CSS rules that relate to the #marker-nav element. The segment 
of CSS that you need to remove is shown (summarized) here: 

/* marker navigation bar */ 
#marker-nav { 

/* set generál color and style */ 

background: rgba(33, 69, 123, 0.8); 

color: whitej 

font-weight: bold; 

text-shadow: ipx ipx ipx rgba(50j 50, 50, O.85); 
text-align: center; 

/* initialize positioning and layout */ 

position: absolute; 

top: 20px; 

z-index: 90; 

width: 90%; 

margin: O 2%; 

padding: iBpx 3% lOpx; 

/* add the 'mandatory' border rádius */ 
border: 2px solid rgba(255, 255, 255, 0.2); 
-webkit-border-radius: I2px; 



#marker-nav span.has-detail { 
text-decoration: underline; 

} 

Once these changes are complete, running Moundz in the emulátor shouid display as it 
did before. Figuře 12-2 shows an example of what you shouid see. 
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Figuře 1 2-2. The login screen for Moundz has been restored in our jQuery Mobile version. 

While the screen displays correctly, things will not work as they shouid yet. An attempt 
to authenticate will simply return you to the splash screen again, as in the previous 
chapter we just disabled handling of the authenticated event on our GEOMINER . Bridge 
instance. It is quite trivial to reinstate, however, as shown in the following code: 

MOUNDZ = (functionO { 



var module = { 

addMarker: addMarker, 
clearMarkers: clearMarkers, 

findResources: f indResources, 

init: f unction(zoo[nLevel) { 

// initialize the geominer bridge 
geominer = new GEOMINER. Bridge({ 

app: 'moundz', 

login: '#login' 

}); 

$(geominer).bind( 'authenticated', f unction(evt) { 
$('#splash').hide(); 
$( ' .noauth' ) .removeClass( 'noauth ' ); 

// run the app 

run(zoomLevel, new google. maps.LatLng(-33. 86, 151.21)); 

}); 
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// initialize the screen 
initScreenO; 



}; 

return module; 

})(); 

AIthough we were simply able to uncomment the actual authenticated event handler, we 
also need to tweak the display logic a little. While we do still want to hide the #splash 
div once we have successfully authenticated, we no longer want to display the #app div 
when completed. Instead, we want to remove any instances of the noauth class from 
divs that have been initialized with that in the HTML. 

Additionally, to help keep the chapter flowing, we have left the mock location in for the 
time being (as specified in the second parameter of the run function), but we will rennove 
it before the end of the chapter so we can go back to using the location detection 
routines. 

Once these modifications have been completed successfully, it shouid be possible to 
log into Moundz as we were doing in Chapter 10. Figuře 12-3 shows an example of how 
this appears with the updated jQuery Mobile interface. 
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Figuře 1 2-3. Moundz displaying markers in the jQuery Mobile interface — some polishing is still required, though. 



With that complete, we are on the road to being able to polish up our application and 
add some of those outstanding features. On the to-do list we have: 
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■ Cleaning up the alignment of the bottom buttons to achieve a nice, 
centered alignment and prevent wrapping 

■ Adding the ability for a user to collect resources 

Improving Navigation Layout 

While we won't spend too much time on it, it is worth having a quicl< look at ways that 
we can improve how those navigation controis formát. As shown in Figuře 12-3, the 
alignment of the controis is not optimal; also, it is possible for the Next button to wrap 
over to the next line when a long pláce name is found. 

The good news is that half the work is aiready taken care of for us thanks to the CSS 
that is packaged with jQuery Mobile— any text that cannot fit into a button of a particular 
fixed width (or maximum width) will be shortened with an ellipsis (a series of three dots; 
see http://en.wikipedia.org/wiki/Ellipsis). All we have to do is appropriately limit 
the button sizes. 

To achieve this, we will use another new CSS3 feature— the flexible box layout (see 
www.w3.org/TR/css3-flexbox) — combined with some standard CSS rules to control 
HTML element width. 

No changes are required to our HTML, so simply add the following CSS to the end of 
the moundz.css file: 

/* navigation control visual treatment */ 

#tnarker-nav a { 
max-width: 32%; 

} 

#ínarker-nav a.left, #inarker-nav a.right { 
width: 90px; 

} 

#marker-nav { 

display: -webkit-box; 
-webkit-box-pack: center; 

} 

Now, there is nothing overly complicated here. We have a CSS class that telis anchor 
tags within the #marker-nav element to have a width no greater than 32 percent (of the 
parent element). We then override that style for any anchors with lef t or right classes 
to set their width manually to gopx. 

Finally, we specify a rule that implements some CSS3 flexbox magie for the #marker-nav 
element. First, we modify the display to -webkit-box (as per the previous CSS3, we 
prepend the proprietary webkit prefix) and then tell the element that we want to display 
any child elements in the center of the control. This is done using the -webkit-box-pack 
rule, and it is set to the value of center. 
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NOTE: Using the CSS3 flexible box layout is a good option here, but you might be looking at the 
code and HTML elements involved and wondering why a simple text-align rule wasn't used. 
In truth, it couid have been in this particular case; however, it doesn't yield as visually pleasing 
results given some of the other CSS rules put in pláce by jQuery Mobile. 

As such, we have gone with the CSS3 flexible box layout approach. Here's some further reading 
on the topič: www.ht1nl5rocks.con1/tutorials/flexbox/quick. 



Once we have made our changes to the CSS, the button alignment shouid be much 
more visually pleasing — as is displayed in Figuře 12-4. 
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Figuře 12-4. With some CSS we can constrain our button sizes, replacing overflow text with an ellipsis. 



With the navigation buttons more attractively displayed, having that Next arrow left- 
aligned on the button is standing out more than it did before. Time to do something 
about that. Thankfully, this is made super simple by jQuery Mobile. 

Locate the anchor tag for the Next button in the HTML and simply add a data-iconpos 
attribute with the value of right to the HTML. 

<div id="marker-nav" data-role="controlgroup" data-type="horizontal"> 

<a href="#" data-role="button" data-icon="arrow-l" class="left">Previous</a> 

<a href="#[narker-detail" data-role="button">Info</a> 

<a href="#" data-role="button" data-icon="arrow-r" data-iconpos="right" 

class= "right" >Next</a> 

</div> 
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With this trivial change in pláce, our navigation button now displays with the icon to the 
right of the button, as shown in Figuře 12-5. 
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Figuře 1 2-5. Our navigation bar is starting to look pretty polisiied — time to work on the rest of tlie app. 

Gathering Resources 

Wltln the front screen of the application starting to come together, iťs time to work on 
some of those features that we left out of the build so far. One of the most important is 
the ability to gather our resources for the game. These resources couid be whatever you 
need them to be for your geosocial game. If you are building a classic stratégy game, 
then the resources couId be things lil<e wood, coal, or gold. But they couId just as easily 
be something completely different— it really is up to you. For the purposes of our sample 
here, however, we will just keep the term generic. 

Building tlie Resource Details Screen 

Before we implement functionality for gathering the resources, though, there are a few 
things that we need to do in the main moundz. js file that will assist us with managing the 
State of the application. Until now, we have simply been displaying some debug-level 
Information when a marker has been selected, and that really is no longer appropriate 
for what we need to do. The following code shows the modifications required to the 
moundz. js file to assist with keeping track of resource data in the application. 

MOUNDZ = (functionO { 

// initialize constants 
var DEFAULT_ZOOM = 8, 




GEOMINER_MOUNDZ_URL = 'http://api.geominer.net/vl/moundz'; 

// initialize variables 
var geominer = nullj 

markerData = {}, 
currentResource = ' ' , 

posWatchld = 0; 

/* priváte functions */ 

function activateMarker(marker) { 

// iterate through the markers and set to the inactive image 
for (var ii = 0; ii < markers. length; ii++) { 

markers [ii] . setIcon( ' img/pin-inactive.png' ); 
} // for 

// update the specified marker's icon to the active image 
marker.setIcon( ' img/pin-active.png' ); 

// update the navbar title using jOuery 
$( '#marker-nav a[href="#marker-detail"] ' ) 
.find( ' .ui-btn-texť ) 

. html (marker . getTitle( ) ) ; 

// update the active marker title 
currentResource = marker. getTitle()j 

// update the marker navigation controls 
updateMarkerNav(getMarkerIndex(marker)); 
} // activateMarker 

function markResources(resourceType, deposits) { 
for (var ii = 0; ii < deposits. length; ii++) { 
// add the marker for the resource deposit 
addMarker( 

new google. maps. LatLng(deposits[ii] .lat, deposits[ii] .Ing), 
deposits[ii] .name, 
deposits[ii] ); 

} // for 
} // markResources 



/* exported functions */ 

function addMarker(positionj title, data) { 

// create a new marker and display it on the map 
var marker = new google. maps. Marker({ 

position: position, 

map: map, 

title: title, 

icon: 'img/pin-inactive.png' 

}); 

markerPosition = position; 
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// save the marker data 
markerData[title] = data; 

// add the marker to the array of markers 
markers . push (marker) ; 

// capture touch click events for the created marker 
google. maps.event.addListener(markerj 'click' j function() { 

// activate the clicked marker 

activateMarker (marker); 

}); 

} // addMarker 



var module = { 

}; 

return module; 

})(); 

These changes to the code have been put in pláce to facilitate storing the data received 
from the Geominer API. While storing some arbitrary content was useful back when we 
were putting together our boilerpiate mapping application, we have outgrown it here. 

The changes to the addMarker and markResources functions are simple iniine changes, in 
which we change references of content to data (e.g., markerContent becomes 
markerData). 

The changes to the activateMarker function do a little more. Previously, the 
activateMarker function set the active nnarker (and the inactive markers) to have the 
correct icon, updated the marker title in the nav button, and also updated the marker 
detail content and attached relevant events. Now that we are working with data instead 
of the marker content, it makes sense for us to handle things slightly differently. The 
code for updating the #marker-detail div content and binding and unbinding to the 
events of the appropriate links has been removed, and has been replaced with a simple 
call to set the currentResource variable to the title of the selected marker. 

With the currentResource variable in pláce, we can move on to updating the details for 
that resource in the #marker-detail display. Leťs begin by making some changes to our 
index.html file: 

<div id="marker-detail" class="noauth" data-role="page"> 
<div data-role="header"> 

<hl>Resource Details</hl> 
</div> 

<div data-role=' content '> 
<h2></h2> 

<div id="resavail"></div> 
<div data-role="f ieldcontain"> 

<label for="slider">Amount to Gather :</label> 

<input type="range" name="slider" id="slider" value="l" min="l" max="5" /> 
</div> 

<a id="btnGather" href="#" data-role="button">Gather</a> 
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</div> 
</div> 

Here we see some more jQuery Mobile code coming into play. For instance, notice the 
div marked with the data-role="fieldcontain" attribute. This telis jQuery IVlobile tínat 
we are dropping in a section of form controls. Additionally, note the use of the new 
HTML5 range input type (www. w3.org/TR/html-marl<up/input. range.html), which jQuery 
Mobile replaces with its own interpretation of the range control by way of an attractive 
graphical slider. With this HTML in pláce, our Resource Details screen will look similar to 
Figuře 12-6. 
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Figuře 1 2-6. jQuery Mobile does a very nice job of providing a simple, clean mobiie Ul. 



OK, iťs time to actually show some useful Information on this screen. We will do this by 
detecting the user navigating to the Resource Details screen by capturing tap events on 
relevant links. The following modifications to moundz. js demonstrate how we do this: 

MOUNDZ = (functionO { 

// initialize variables 
var geominer = null, 

supportsTouch = 'ontouchstarť in window; 

/* priváte functions */ 



function updateResourceDetailsO { 

var currentData = markerData[currentResource]; 



if (currentData) { 

$('#marker-detail h2' ) .html(currentData.natiie); 
} // if 
} // updateResourceDetails 

/* exported functions */ 



function initScreen() { 

// size the canvas to the height of the page minus the header 
$('#map_canvas' ) .height( 
$('#main').height() - 

$('#main div[data-role="header"] ' ).outerHeight() - 
$('#main div[data-role="footer"] ').outerHeight() - 30 

); 

// bind to the marker detail tap event 

$Ca[href="#marker-detail"]').live(supportsTouch ? 'tap' : 'click', 
updateResourceDetails) ; 

} // initScreen 



var module = { 

}; 

return module; 

})(); 

This code performs a couple of functions: 

1. It defines a new function, updateResourceDetails, which uses the 
currentResource variable that we defined earlier to retrieve the data on the 
resource. This data is then used to update the app display; in this case, we are 
simply updating the header within the display, but we will add more functionality 
very soon. 

2. The initScreen function is modified to attach an event handler to any links that 
direct the user to the #marker-detail screen. This is done using the jQuery live 
function (http://api.jquery.com/live), which nneans that the event handler is put 
in pláce for any elements (including ones that might be dynamically created later) 
matching the selector. 

Also worth noting in this code is the use of the ternary (or elvis) operátor with the 
supportsTouch variable. This, combined with the initialization of the supportsTouch 
variable at the start of the module, provides us with a useful mechanism that will allow 
US to test our application both on mobile and desktop browsers. It does this by 
appropriately attaching to either the tap or the click event handler, depending on 
whether the current device supports touch interaction. 



This is very useful during the development of mobile web applications, as debugging 
witin a desktop browser is generally a more pleasant experience tínán working witin the 
Android debugging console— see Appendix A for more information on tine topič. 

With the code in pláce, tapping the Resource Details button in the navigation bar will 
show US a Resource Details screen similar to that shown in Figuře 12-7. 
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Figuře 1 2-7. Our Resource Details screen is now dynamically updated. 

Now that we have the groundwork in pláce to update the display of the Resource Details 
screen, iťs time to make it pretty— we are definitely overdue for some more CSS3 
gradients. 

The following CSS (added to the end of moundz.css) gets us partway there: 

/* resource details screen styles */ 

#[narl<er-detail h2 { 
text-align: center; 
margin: O O lOpx; 
color: #777; 

} 

#resavail { 

bacl<ground: #333 -webl<it-gradient(linear, left top, right top, from(#099), to(#OAO)) 
no-repeat; 

border: 2px #333 solid; 
-webl<it-border-radius: 8px; 
-webl<it-box-shadow: #555 O ipx 2px; 
height: 20px; 
font: bold 0.9em Arial; 
letter-spacing: 3px; 
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} 



text-align: center; 
color: white; 
padding: 5px O 2px; 
text-shadow: nonej 



With the CSS applied, the Resource Details screen shouid appear similar to Figuře 12-8 
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Figuře 1 2-8. Our Resource Details screen is starting to look good, but what is that under the resource name? 



While the CSS makes things look a little prettier, that bar beneath the resource name is 
a bit of a mystery. What is it for? WeII, we are going to turn that into a bar that displays 
the current resource availability for the resource by adding some additional code to the 
updateResourceDetails function that we recently created. 

function updateResourceDetailsO { 

var currentData = marl<erData[currentResource]; 
if (currentData) { 
var percAvail = 0; 

// determine the resource available percentage 
if (currentData. total !== 0) { 

percAvail = Math.round((currentData.avail / currentData. total) * I00)j 
} // if 

$( ' #marl<er-detail In2 ' ) . html (currentData . name) ; 

$( '#resavail' ) 

.html(currentData.avail + ' / ' + currentData. total) 
.css( ' -webkit-background-size' , percAvail + '% 100%'); 

} // if 
} // updateResourceDetails 




In the preceding code you shouid be able to see where we are tapping into some of the 
extra data that is returned from the Geominer API. With that data we do two things: 

1. Calculate the percentage of resources available using some trivial math. That 
percentage value is then used to dynamically apply a -webkit-background-size 
style to the #resavail div. Our particular definition for the style instructs the div 
to slze the background image (note that gradients are treated as images) to a 
calculated percentage of the width and 100 percent of the height. Essentially, we 
have created a simple progress bar with very little code at all. 

2. Update the content of the ttresavail div to display a textual description of the 
quantity of resource available at the particular location. 

After implementing this JavaScript code, our Resource Details screen will be similar to 
Figuře 12-9. 
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Figuře 1 2-9. The Resource Details screen showing that this location aiready has many resources gathered 

This brings us to the point where our Resource Details screen is showing us some 
sensible, reasonably weil-presented information. Iťs now time to look at gathering some 
resources. 



Using Geominer for Resource Tracicing 

Once again, we will make use of the Geominer API to perform the actual gathering of 
resources. Behind the scenes Geominer will track the amount of resources that have 
been gathered from a particular location and subtract that amount from the total amount 
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of resources (remember that these are in fact Gowalla check-ins) to report available 
quantities. For Geominer to be able to track these quantities, we will need to tell it we 
are gathering resources— and that is the purpose of this section. 

The following code shows the modifications required to moundz. js to hook into the 
Geominer API functionality and start gathering resources: 

MOUNDZ = (functionO { 



/* priváte functions */ 



function gatherResourceO { 

var currentData = fnarkerData[currentResource] ; 
if (currentData && geominer) { 
var qty = $( '#slider' ) .val(); 

geominer. gather(currentData. id, qty, function(totalCathered) { 
// update the quantity available 

currentData. avail = Math.max(currentData.total - totalGathered, O); 

// if the resource is still the same, then update the display 
if (currentData. name === currentResource) { 

updateResourceDetailsO; 
} // if 

}); 

} // if 
} // gatherResource 



/* exported functions */ 



function initScreenO { 



$( '#btnCather ' ) .live(supportsTouch ? 'tap' : 'click', gatherResource); 
} // initScreen 



var module = { 

}; 

return module; 

})(); 

In this code we once again attach a tap handler to the Gather button on the Resource 
Details screen. When the user taps this button, the gatherResource function will then be 
called, which simply makes use of the bundled Geominer API via the exported gather 
function call. We pass the ID of the resource the quantity of resources that we wish to 
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gather and a callback that will receive the total quantity (from all users and previous 
gather operations) of resources that has been gathered for that particular resource. 

With the Information that we receive back, we can then update our own local data for 
the resource in an attempt to keep the two in syne. Shouid we receive a response from 
the server fast enough (which we shouid), the current resource screen will be updated to 
reflect the revised quantity of resources avallable. 

As mentloned in previous chapters, if you are Interested In what Geominer does behind 
the scenes, you can look at the source on GItHub, at the followlng URL: 

https : / / github . com/ sidelab/geominer . 

Remember, though, that Geominer is a bit of a work-ln-progress, and has been bulit to 
support the samples In this book, so It wouid require a good deal of work before It couid 
be considered a truly useful API. 

While there is still so much that we couId potentlally do, and so much that needs to be 
done to make Moundz a useful playable game, this book wouId nevěr have been 
published if we didn't draw the sample to a close somewhere. We still have work to do 
In the chapter, but, as far as Implementing functlonallty In the Moundz appllcatlon, this Is 
where we will draw things to a close. 



NOTE: If you are Interested in how to take Moundz further or have questlons about how 
Geominer works under the hood, feel free to join the Pro Android Web Apps group and ask 
questions there (http://groups.google.com/group/pro-android-web-apps). We 
try to find tlme to answer any questlons posted. 




Packaging Moundz As a Native Application 

Now that Moundz has all the features that we are going to Implement In the context of the 
book, Iťs tlme to package It up as a native appllcatlon using PhoneGap. We won't go 
through the entire process again here, as we covered it pretty thoroughiy In Chapter 9. 



Bundling for PhoneGap 

First, we need to create a directory for our Moundz appllcatlon. As in Chapter 9, this is 
done most simply by copylng an existing project to a new moundz directory. Figuře 12-10 
shows an example of what you shouid see after the copy operation. 
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Figuře 1 2-1 0. As discussed in Chapter 9, starting a new PhoneGap projed is a simple copy-and-paste operation. 

In keeping with our theme of copy-and-paste deployment, taking our Moundz source 
code and integrating that into our Moundz project is also simple. If you recall from 
CInapter 9, all that is required is to take the HTIVIL files that we have in our moundz- jqm 
folder and copy them to the assets/www folder within our new Moundz PhoneGap 
project. After connpleting the process, you shouid have a folder structure that resennbies 
Figura 12-11. 
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Figuře 1 2-1 1 . Our HTML, CSS, and JavaScript assets are copied to the assets/www folder of the PhoneGap 
projed 



We now need to update references in the application to Moundz from their previous 
values. For detailed instructions on how to do this, revisit the Chapter 9 section 
"Tweaking the Sample PhoneGap Project." 

After we have completed these steps and then installed the application to the emulátor 
(remember ant debug install in the project folder), you shouid be able to open the 
emulátor and see a IVIoundz application in the Android application launcher. Figuře 12-12 
shows an example of what you will likely see. 
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Figuře 1 2-1 2. We have successfully installed our application into the emulátor, but iťs time for a different icon. 

Supplying an Application Launclier Icon 

One thing that we didn't cover in Chapter 9 was customizing parts of the PhoneGap 
application beyond just tine name references. If we are going to deploy an application to 
tine Android marketplace, iťs probably a good idea to provide a custom icon for our 
application ratiner than simply use the PhoneGap default icon. 

With regard to application icons, Google provide some excellent documentation that 
covers some of the dos and don'ts around icons in your application. This is definitely 
worth a read and can be found at the following URL: 

http://developer.android.com/guide/practices/ui_guidelines/icon_design.html. 

Additionally, if you have Photoshop (http://adobe.com/photoshop) available, then 
Google also provide a useful template for building application icons, which can be found 
with the icon design guidelines that we referenced in the previous paragraph. 

Now, we aren't going to go through the process of creating an application icon here, as 
this is more of a design-related task than a programming one, but you can use a variety 
of different tools to create the icon as long as a file named icon.png is generated at the 
end of the process. Additionally, as per the icon design guidelines provided by Google 3, 
different resolutions of the launcher icon shouid be supplied: 

■ A 72x72-pixel icon . png file for high-dpi (hdpi) devices 

■ A 48x48-pixel icon . png file for medium-dpi (mdpi) devices 

■ A 36x36-pixel icon . png file for low-dpi (Idpi) devices 




Once you have your relevant icon files, these are simply copied to the relevant 
res/drawable-?dpi folder (where ?dpi wouid be hdpi, mdpi, or Idpi, depending on the 
icon size). Figuře 1 2-1 3 shows where each of the files have been placed in our working 
copy of the sample, and, while iťs not visible in the screenshot, the 72-pixel image is in 
the drawable-hdpi folder, the 48-pixel image is in the drawable-mdpi folder, and the 36- 
pixel image is in the drawable-ldpi folder. 
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Figuře 1 2-1 3. Our updated icon.png file is placed in the res area of the projed 



With the icon in pláce, we are ready to rebuild and reinstall the application to the 
emulátor. If everything has gone to pian, you shouid see an updated launcher icon, as 
shown in Figuře 12-14. 



CHAPTER 12: Polishing and Packaging an App for Release 



3= II m 3:30 



Browser 


Calculator 


Camera 


Clock 


M 

Contacts 


#• 

Custom 
Locate 


n- 

DevToois 


■ 

Dawnioads 


■ 


n 


P 




Email 


Gallery 


Messaging 


Moundz 



Mílsk. Phane Search Settings 




Figuře 1 2-1 4. Our updated launcher icon now displays in the Android application launcher. 

With our application now lool<ing tine part, there is one more tining we have to do before 
iťs ready to pacl<age up and sinip to tlie Android marketplace. 

Tweaking Application Permissions 

If you have ever installed a native Android application, you are probably familiar with the 
screen that telis you what pernnissions the application is asking for before you complete 
the installation proceduře. Figuře 12-15 shows a screenshot of the permissions 
installation screen for the native Gowalla application, which gives you an idea of the kind 
of thing that applications request on installation. 
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Figuře 1 2-1 5. The Gowalla installation screen provides an example of the permissions that an application may 
request. 



Now, we really don't want to have an application tínat requests permissions for 
operations that it does not use. This is because users may have an objection to granting 
certain permissions, and in this oase the more permissions our application requests, the 
more chance it has of being rejected by a user during installation. As such, it is best to 
keep the required permissions to a minimum. 

As part of the default sample PhoneGap project, we have an AndroidManifest.xml file 
that requests a large number of permissions, and most of these aren't required for 
Moundz. For example, the following is an excerpt from the AndroidManifest.xml file 
showing the permission requests. 



<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 
<uses- 



permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 
permission 



android; 
android ; 
android; 
android; 
android; 
android; 
android; 
android; 
android; 
android ; 
android ; 
android ; 
android ; 
android ; 



name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 
name= 



android. permission. CAMERA" /> 

android. permission. VIBRATE" /> 

android . permission .ACCESS_COARSE_LOCATION" /> 

android . permission .ACCESS_FINE_LOCATION" /> 

android . permission .ACCESS_LOCATION_EXTRA_COMMANDS" /> 

android . permission . READ_PHONE_STATE" /> 

android. permission. INTERNET" /> 

android . permission . RECEIVE_SMS" /> 

android . permission . RECORD_AUDIO" /> 

android . permission . MODIFY_AUDIO_SETTINGS" /> 

android . permission . READCONTACTS" /> 

android . permission . WRITE_CONTACTS" /> 

android . permission . WRITE_EXTERNAL_STORAGE " /> 

android. permission. ACCESS_NETWORK_STATE" /> 



While we won't go into the specifics of every permission here, details on what particular 
permissions provide can be found on the following page in the Android developer docs: 
http://developer.android.com/reference/android/Manifest.permission.html. 

For the purposes of Moundz, it is pretty safe to remove the majority of these 
permissions and just reduce it to the permissions that provide our application web 
access and allow us to access location information. The reduced set of permissions 
wouid be something more like this: 

<uses-permission android :name="android. permission. ACCESS_COARSE_LOCATION" /> 
<uses-permission android : name="android . permission .ACCESS_FINE_LOCATION" /> 
<uses-permission android : name="android . permission .ACCESS_LOCATION_EXTRA_COMMANDS" /> 
<uses- permission android : name= "android . permission . INTERNET" /> 

Depending on the type of application you are building, additional permissions may or 
may not be required, which is probably why they are included in the default 
Androidl^anifest.xml file. 

PhoneGap, Authentication, and Intents 

Before our application is ready for native deployment, we need to make some 
modifications to the way the authentication flow in the application behaves— or, rather, 
we need to properly equip our application to be able to respond to the authentication 
process that we put in pláce back in Chapter 10. 

Our Previous Web Authentication Fiow 

Our finál authentication process involved opening a new browser window, which is 
where we let Geominer and Twitter work through the authentication process before 
passing control back to our main Moundz web application. While this worked 
seamlessiy in a browser environment, it doesn't work as effectively when we have our 
web application wrapped in a native application. Why? Thaťs an excellent question— 
leťs take a look. 

In our web application, our authentication flow went something like this: 

1. The user clicks the "Sign in with Twitter" button, a session ID is created within 
Moundz, and a new browser window is opened to the Geominer session 
initialization script. 

2. Geominer handles the "OAuth dance" with Twitter, at which point the user may be 
asked to validate that they are OK with allowing Geominer to log them in. 

3. Once the authentication process is completed, the new browser window is 
dosed. 




4. At this point, the user is implicitly returned (when the browser window is dosed, 
the last browser window is refocused) to our IVloundz application window. Behind 
the scenes, Moundz has been communicating with the Geominer API in the 
background and has determined that we are authenticated. It then sends us to 
the application map. 

Once Moundz is wrapped in a native application, the process fails at step 3 due to the 
way opening a new window is handled from within a PhoneGap application. Essentially, 
the WebView that is used in a PhoneGap application represents a single browser 
window, and, if any links are opened that require a new window, the native Android 
browser (not the application itself) handles this. This is understandable and the right way 
to handle such requests; however, it does have an impact when Geominer attempts to 
close the browser window in step 3. Essentially, it fails, and the user is left in the native 
browser on the Geominer authentication screen with no obvious way to get back— not 
exactly optimal usability. 

The good news is that we are able to implement a workaround; however, we do have to 
work at a native level to do this. Don't worry, though— the process is quite simple and 
won't involve having to write any Java code. 

An Overview of Android Intents 

Android intents are structured mechanisms for passing messages between applications 
on the Android platform. Essentially, each application runs in its own sandbox and 
doesn't have access to another application's data— which is fair enough. To 
communicate with another application, an intent is sent to the Android OS itself, and, if 
one or more applications are configured to respond to that intent, then the OS provides 
them an opportunity to do so. 

While intents are a native application concept, they make a lot of sense from a web 
developer's perspective, primarily because they respect the web URI scheme 
(http://en.wikipedia.org/wiki/URI_scheme) naming conventions. While we aren't 
interested in how to use intents from the perspective of native application development, 
using intents can provide us with an almost seamless way to transition from a web page 
back into our native application. In our particular case, we are providing a transition from 
the Twitter authentication process, back into the PhoneGap application wrapper for 
Moundz. 

If you own and use an Android device, then you have probably experienced this 
aiready— for example, if you were browsing a web page, and then after clicking a link 
were taken to one of the native Android apps, as if by magie. Both the Android Market 
and YouTube use intents in this way. 

So, leťs see how complicated it is to have Moundz respond to some Android intents. 
The first thing we need to do is modify the AndroidManifest.xml file that resides in the 
root directory of our Moundz PhoneGap project. In this file, we will be adding an 
additional intent-filter to the application definition: 

opplication android : icon="@drawable/icon" android : label="|a)string/app_naine" 
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android : debuggable="true" > 
octivity android:name=" .Moundz" 

android : label="@string/app_name" 
android : conf igChanges="orientation | keyboardHidden"> 
<intent-f ilter> 

<action android:na[ne="android.intent.action.MAIN" /> 
<category android:name="android.intent.category.LAUNCHER" /> 
</intent-f ilter> 
<intent-filter> 

oction android : naffle= "android . intent . action . VIEW"></action> 
<category android : name="android . intent . category . DEFAULT" ></category> 
<category android :name="android. intent. category. BROWSABLE"></category> 
<data android :host="moundz" android :scheme="content"></data> 
</intent-filter> 
</activity> 
</application> 

Our new intent-filter definition is setting up Moundz to receive intents with the VIEW 
action, and we are marking our filter with the categories of DEFAULT and BROWSABLE. Both 
of these category definitions are required to have the intent filter work properly from the 
native web browser. 

Finally, the intent-filter definition contains a data tag that provides information on 
how the URI scheme will look when placed in an HTML anchor. For instance, our 
definition specifies a host of moundz and a schenne of content, which means that links in 
web pages that start with content: //moundz are going to match this filter, and the 
Moundz native application wouid be opened in response to these links being clicked. 

NOTE: Tlie content URI scheme is an official registered URI scheme that maps to content 
providers for the Android platform. Note that it is also possible to use a custom scheme (e.g., we 
have URIs starting with moundz : //); however, it is often discouraged, as URI schemes are 
meant to be unique, and this uniqueness is controlled through various Internet standards bodies. 

Additionally, it is also possible to register the filter using the HTTP (or HTTPS) scheme shouid you 
want to allow users to either complete the action using the Android browser or via a native 
application. If we had actually deployed to a public URL, then this might be an excellent way to 
go, but at this stage we are focusing on a deployment through PhoneGap, so the content scheme 1 
is probably the best fit. I 

To test our new filter, we simply need to create a very simply web page with a link that 
matches the rule specified in the intent-filter: 

<!DOCTYPE html> 

<html> 

<head> 

<title>Intent Test</title> 

<meta name="viewport" content="initial-scale=l.O, user-scalable=no" /> 

</head> 

<body> 

<a href="content://moundz/test">Moundz Local Test</a> 
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</body> 
</html> 

All right, leťs give it a go. Save the preceding code and then browse to it using the 
native Android browser. You shouid see a simple link and, when you activate the link, 
the native Moundz application shouid be launched. Figuře 12-16 displays an example of 
what you shouid see. 



SBDQ 7:01 m 



M http://1 0.1. 1.3:8080/5.. 



Moundz Local Test 



llIfflQ 7:05 PIVl 



Welcome to 

moumz 



Press the 'Sign in with Twitter' button 
below to get started playing. 



Figuře 12-16. Clicking the test link takés us directlyinto the Moundz application. 

Excellent, it worked. With that functionality, we shouid be able to make some tweaks to 
our Moundz application code and have it take appropriate action in response to the 
intents. We will, however, need a little help. 



Using PhoneGap Plug-lns to Handle Intents 

We made a commitment earlier regarding not having to write Java code to work with the 
intents from within PhoneGap, and, despite intents being a native Android OS feature, 
we are going to be able to keep that promise. This is all thanks to the fact that someone 
has aiready done the hard work for us. In this section, we will be making use of a 
PhoneGap plug-in called Webintent, which was created by Boris Smus. Boris has 
written a blog post on his motivations for writing Webintent and it is weil worth a read 
(see www. borismus . com/android-phonegap-plugins). 

Essentially, Boris's plug-in provides the ability to invoke Android intents from your 
JavaScript, and also to respond to them if your application has intercepted and 
responded to an intent. Installation of the plug-in is very simple: 
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1. Download the Webintent. java and webintent. js files from the following github 
repository: https://github.com/borismus/phonegap- 
plugins/tree/master/Android/Weblntent. 

2. Tae the webintent. js filé and pláce that in the assets/www folder of the Moundz 
PhoneGap project. 

3. Take the Webintent. java file and pláce that In a new borismus directory in the 
src/com folder of the PhoneGap project. 



Figuře 12-17 provides a screenshot of how the application folder shouid look after 
completing these steps. 
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Figuře 12-17. Our Moundz PhoneGap project folder after adding the Webintent plug-in files 



With the plug-in files in their correct pláce, iťs time to wire everything up. The first step 
in this process is including the phonegap. js file in the project and also adding a script 
include for the webintent. js file. At the same time, we'll also move the script include for 
moundz. js to just before the closing body tag, as this is required for trapping particular 
events. 

Additionally, while we are making modifications to the index.html file, we will remove 
the body onload event handler, as we now need to start making some RhoneGap- 
specific modifications to our code. 

<!DOCTYPE html> 

<html> 

<head> 




<script type="text/javascript" src="phonegap. js"></script> 
<script type="text/javascript" src="webintent . js"></script> 

<!-- 

<script type= "text/javascript "> 
function initializeO { 

MOUNDZ.initO; 
} // initialize 
</script> 
--> 

</head> 
<body> 

<script type="text/javascript" src="moundz. ]s"></script> 

</body> 

</html> 



MAINTAINING A SINGLE CODEBASE 



Until now we have maintained a single code base for an application version that couid be deployed to both 
the web or a native application using PhoneGap. Now we are starting to make modifications that are 
specific to a PhoneGap version. 

In our sample applications, we wlll simply be removing and adding code to suit our PhoneGap version, and 
having that code live in a locatlon separate from our previous web-oniy version. If you are worklng on a 
real-worid project, however, and find yourself In a similar situatlon, then look to alternativě solutlons that 
allow you to maintain a single code base while stlll allowing parts of the code to be customized for certain 
situatlons. 

One way this couId be achleved Is through implementing a bulid process using previously mentloned tools 
like Ant or Rake. The bulid script selectively combines particular JavaScript files Into a single JavaScript 
flle designed for a particular platform distributlon. 

Another optlon is through using detection techniques within your JavaScript code. Glven that we do not 
Include phonegap. js in our pure web version of the application, we can make some runtime checks 
around the availability of PhoneGap within our moundz. js file. ThIs allows us to maintain a single version 
of our core JavaScript flles, and simply requires some small tweaks to the application HTML files (which 
are llkely to differ somewhat anyway). 



Wlth the changes to our index.html file done, we now turn our attentlon to the 
moundz. js flle. Here, we wlll make sonne modifications to attach to the custom 
PhoneGap deviceReady event rather than onload. This wlll ensure that PhoneGap- 
dependent code wlll oniy run once PhoneGap has been properly initialized. Additionally, 
we will wire In the Webintent plug-in to monitor for detalls that wlll be passed through If 
the application Is launched using a native Intent. 

MOUNDZ = (functionO { 

/* priváte functions */ 
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function parseUrlParams(url) { 

return {}; 
} II parseUrlParams 

var module = { 

}; 

// bind to the PhoneGap deviceReady event 
document.addEventListener('deviceReady', function() { 

window.plugins.webintent.getDataString(null, function(dataString) { 

module . init (parseUrlParams (dataString) ) ; 
}, functionO { 

module. init(); 

}); 

}, falše); 

return module; 

})(); 

In the preceding code, we are making two changes to ensure that we properly handle 
the PhoneGap initialization: 

1. Just before we return the module definition at the end of moundz. js, we add an 
event listener for the deviceReady event that is triggered by PhoneGap. Within this 
event handler, we ask the Webintent plug-ln to provide us details on any 
additional data that it has received. 

If the Moundz application has been started directly from the launcher, this call will 
simply pass a null value through; however, if the application has been called from 
a URL in the browser (such as our test page), this will be available to the native 
application. 

2. Once we have successfully retrieved the value passed through, this value is 
passed through a new function called parseUrlParams before being passed on to 
our init method. For the moment, this function is just a placeholder and simply 
returns an empty object literal; however, we will add some meaningful code next. 

The code we need to add to our parseUrlParams function will allow our application to 
translate URL query string parameters into a JavaScript object literal, which will then be 
interpreted in the MOUNDZ. init module function. 

The following is the code required to have parseUrlParams perform that operation: 

function parseUrlParams(url) { 

var matches = /'^.*?\?(.*)$/.exec(url), 

keyPairs = matches ? matches[l] .split( '&' ) : [], 
params = {}; 

// iterate through the key pairs we found 




for (var ii = 0; ii < keyPairs.length; ii++) { 

// split the pair on the = as we are only going to process these 
var pair = keyPairs[ii] .split('=' ); 

// update the parameters 

params[pair[o] ] = pair.length > 1 ? pair[l] : null; 
} // for 

return params; 
} // parseUrlParams 

This may not be the most readable code in the worid, being littered with regular 
expressions and ternary operators, but its purpose is simple. As previously stated, 
parseUrlParams needs to extract that query string parameters from a URL and return 
them in a JavaScript object literal. 

For instance, if we passed the following URL to the function: 

http: //test. com/test.htm?paraml=foo8iparam2=bar, then the parseUrlParams function 
wouid return an object literal of the following: 

{ 

parami: 'foo', 
param2: 'bar' 

} 

Once we have our query string parameters in that formát, we can pass them to a 
modified version of our MOUNDZ.init function to be processed intelligently. Our modified 
init function follows: 

MOUNDZ = (functionO { 



var module = { 



init: function(args) { 

// initialize the parameters 
args = $.extend({ 

zoomLevel: null 
}, params); 

// initialize the geominer bridge 
geominer = new GEOMINER. Bridge($.extend({ 

app: 'moundz', 

login: '#login', 

returnllrl: 'content://moundz/' 
}, args)); 

$(geominer) .bind('authenticated ' j f unction(evt) { 
$('#splash').hide(); 
$( ' .noauth' ) .removeClass( ' noauth ' ); 

// run the app 

run (args . zoomLevel) ; 

}); 



// initialize the screen 
inltScreen(); 



return module; 

})(); 

Leťs quickly walk through the modifications we are making here; once we are done, 
Moundz will be ready to be packaged up for deployment. 

1. We change the init function from taking a zoomLevel parameter to taking a more 
generic args parameter. This args parameter is then used to pass multiple values 
through (using an object literal) to the constructor of our GEOMINER.Bridge object. 
This is particularly useful when combined with our earlier code that converted the 
uri parameters for the current web page into an object literal (as we will see in 
step 3). 

2. Next, we update the initialization of GEOMINER.Bridge to include a returnUrl 
configuration parameter. This returnUrl parameter will be displayed on the page 
that Geominer presents as the finál step in the Twitter authentication process. So 
now, rather than attempting to close the window, a link will be displayed that we 
can then click to return to the Moundz native application. 

3. Additionally, we pass through the values specifled in the args parameter through 
to the GEOMINER.Bridge using the $.extend function ($.extend is equivalent to 
jOuery.extend). This is a concise and effective way of passing parameters that 
have been sent to our application as part of the Android intent right through to our 
JavaScript module code. 

4. Finally, we modify our call to the run function to remove the mock location that we 
have been using up until this point while developing the application. 

Thaťs it. The coding, tweaks, and refinements are all done. Iťs now time to package this 
application up for Android Market distribution. 

Packaging Our Application for Reiease 

We finally made it. Our coding is done, we have an application icon, and iťs time to 
package the application for deployment. This involves a number of steps: 

1. Building our application in reiease mode, and then signing our application for 
deployment. 



2. Registering for the Android Market. 
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3. Publishing our application to the market. 

In this finál section of this chapter, we will cover what is required to complete step 1 
successfully, and then we will point you in the right direction so you can complete steps 
2 and 3 with your own application once you reach that point. While there are some 
nuances to building the application for release (most of which are now handled during 
the build process), the registration and application-publishing processes are made very 
simple by Google. Additionally, they provide an excellent guide on the topič of 
publishing your application (see 

http: //developer.android.com/guide/publishing/publishing. html). 

The first step in building our application for release is using ant to build a binary of the 
application in release mode. This is achieved by running the following command from 
the Moundz PhoneGap project directory: ant release. 

When run, this command shouid generate output similar to that shown in Figuře 1 2-1 8. 



^ O o Terminal - adb — 100x35 



-package-resources; 

[echo] Packaging resources 

[aapt] Creating full retiource packag?... 

tnuli] (skipping hidden filé '/Volunies/ de^^elopment/proj ects/boDks-code/prowebapps-CDde/brid 

ges/moundz/assets/ . DSStore ' ) 

[nu II] í 5kipping hidden file '/Volumes/ deyelopment/proj ectí/bookí-CDde/prowehapps-code/hrití 

ge^/moundfz/ a^set s/ijww/. D5_5tore ' ] 

[null] ískipping hidden file ' /Volumes/development/proj ects/books-code/prowebapps-code/brid 
ges/nioundz/res/. DS_Store ' ] 

[null] (skipping hidden file '/Volumes/ development/prD] ect s/boDks-CDde/prQwebapps-code/brid 

ges/iiiDuniJz/ res/drawable-hdpi/. DB_Btore ' ) 

[null] (skipping hidden file '/Volumes/ development/^proj ects/books-code/prowebapps— CDde/brid 

ges/moundz/ res/dravable-ldpi/. DS_Store ' ) 

[null] (skipping hidden file ' /'Jalume^/ development/proj ects/boDks-eode/prowehapps-íode/hrid 

ges/fnoundz/res/drawable-ndpi/. DS_Store ' ) 

[null] Warning; And roidManif est* xml already defines debuggable (in http://ochemas,android.com/3 
pk/res/android) ; using existing walue in manifest. 

-package- release: 

[apkbuilder] Creating moundz-unsigned. apk for release... 

-release-prompt-f or-passwD rd : 

-release-nosign; 

[echo] No key.store and key.alias properties found in build* p ropertiea . 

[echo] P Lea se sign /VDlufnes/develDpment/projects/books-code/prowebapps-code/bridges/moundz/bin/ 
riDundz-unsigned.apk manually 

[echo] and run zipalign from the Android SDK tools. 

release: 

BUILD 5UCCE5SFUL 
Total time: 12 seconds 
daniQiTiac: moundz damoS [] 



Figuře 1 2-1 8. Output from running the build in release mode — note the comments regarding signing. 

In this figuře, you may notice some output generated by the Ant build referring to not 
having key.store or key. alias properties available with which to sign our application. 
This has prevented the build script from successfully signing our application, which is 
required if we wish to distribute our application. 



To sign our application, the first thing we must do is generate a priváte key. This can be 
achieved by running the following command (however, you sinouid cinange both the 
keystore and alias to something more appropriate for your own configuration): 

l<eytool -genl<ey -v -l<eystore fny-release-l<ey. l<eystore -alias alias name -l<eyalg RSA - 
l<eysize 2048 -validity 10000 



Running this command shows output similar to that displayed in Figuře 1 2-1 9. 



" Terminal - adb - 100x35 






(Janioriacíinoundz damot keytool -genkey -v -keystore /developAiEnt/projects/mobile/release-key. keystore 


■ 


-alias sidelab -keyalg RSA -keysi2e 2B48 -validity 10000 






Enter keystore pasíword: 






Re-enter new password: 






What is your first and last naflie? 






[Unknown] : Damon Qehlman 






What Í5 the name of ycur organizational unit? 






[Unknownl : Mobile Apps 






What is the name of your organization? 






[Unknown] : Sidelab Pty Ltd 






What is the name of your City oř Locality? 






[Unknown] : Brisbane 






What is the nane of your Stďts oř Province"? 






[Unknown] : QLD 






What is the two-letter country code tor this unit? 






[Unknown] : AU 






l5 CřJ=Dafflon Oehlman, OU^Mobile Apps, D=Sidelab Pty Ltd, L=eri5bane. 5T=0LD, [:=AU 


correct? 




[na]: yeí. 






Generating 2,04B bit RSA key pair and seLf-signed certificate ( SHAlwithRSA) with 


a validity of 10,80 




e days 






tor: CN^Darron Oehlman, QU^Hobile Apps, O^SideLab Pty Ltd, L^Brisbane, 5T^ 


OLD, C-AU 




Enter key password for <sidelab> 






IRETURN if same as keystore pass^ord): 






[Sto ring /development/pfoj ects /mobile/ re lease-key .keystore] 






tíamojnac: moundz damD$ [j 
















A 
T 






"2 



Figuře 12-19. If you don't aiready have one, you will need to generate a priváte key to sign your application. 

With our keystore created, we can now modify our build.properties file and specify its 
location SO the build script can sign our application as part of the build process. With 
our application requirements, there are no additional settings required in this file, so, 
after the key . store and key .alias properties are added, our build . properties file 
shouid look something like the following: 

key . store=/path/to/release-key. keystore 
key.alias=your_alias 

Now, with those settings in pláce, we are ready to attempt rebuilding our application in 
release mode. If everything has gone correctly, you shouid now be prompted for your 
keystore and alias password as part of the build process. Provide the password 
correctly, and your application will be signed and ready for release. Figuře 12-20 shows 
an example of the output that will be generated in a successful build. 




W n ^ Terminal - adb - 100x35 

[nu II] ( skipping hidden f ile ' /Volunies/detfelDpnient/^prDj ect s/boDks-CDde/prowebapps-CDcje/brid J 

ges/ffloundfz/res/. DS_Store ' } 

[nu II] (skipplHQ hidden file '/Volunies/ deyelopment/proj ects/books-code/prowebapps-code/brid 

ges/diounůz/ re5/Clrawable-h[Jpi/,0S_Store ' ) 

[null] (skipping hidden file ' /Volurnes/developfrent/proj ects/books-code/prowebapps-code/brid 
ges/mouncíz/ res/drawabLe-Ldpi/. DS_5tQre ' ) 

[null] (skipping hidden file '/Volumes/ deyelopment/pro] ects/boDks-code/prowebapps-CDde/brid 

ge^/mounrfz/ res/drawable-ndpi/. DS_Store ' ) 

[null] Warning; AndroidManifest^xml already defines debuggable íin http://5chema5.android.coni/a 
pk/res/androidl s using existing walue in manifest. 

-package-rBlease: 

[apkbuilrfer] Creating moundz-unsigned.apk for release... 

-re Lease-proflipt-f or-password: 

[input] Pleaae enter key&tore passwD rd ístorei/dek/elopínent/prajects/nobile/ release-key . keys tore J 



[input] Please enter pas5word for alias '^idelab': 



-release-nosign: 

release: 

[echo] Signing finál apk. ■ . 
[sign] ar] Signing JAR: /^'olunies/development/p roj ects/books-code/prowebapps-code/bridges/mouncíz/bin 
/niQundz-unsigned.apk to /Volumes/development/projects/books-code/prDwebapps-code/bridges/moundz/bin/ 
niDundz-unaligned. apk as sidelab 

[echo] Running zip align on finál apk... 

[echa] Release Package: /VoluifTres/developfnent/proi ects/bDoks-code/prowebappí-code/b ridges/iiiDundz 
/bin/moundz-release. apk 

BUILD 5UCCE5SFUL 
Total tiTTie: 24 seconds 
damoinac : nioundz dano$ Q 



Figuře 1 2-20. After generating a priváte key and providing details to the build script, our build process 
successfully signs our application. 

If you have a look in the bin folder of your Moundz PhoneGap project folder, you shouid 
see a number of files. The most important one as far as a project release is concerned is 
moundz-release.apk. Figuře 12-21 shows an example screenshot of what your bin 
folder might look like. 
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Figuře 1 2-21 . The bin folder of the Moundz PhoneGap projed folder shouid contain a moundz-release.apk filé 
after our successful build. 



Thaťs it. We now have the main application file, which will enable us to publish an 
application to the Android Market. 

If you decide to go down this path with your own Android web apps, then from this point 
you shouid register with the Android Market (http://market.android.coni/publish) and, 
as mentloned previously, fanniliarize yourself with Google's publishing guide that we 
referenced early in this section of the chapter. 

In terms of the tasks that rennain, you will need to gather a few screenshots, make some 
larger icons, and think of some text that describes your application weil to potential 
users. If you are looking to seli applications through the market, then you shouid also 
investigate a Google Merchant account. 

From here on, you enter the land of pictures, text, and promotion. 



Summary 

In this chapter, we covered a lot of materiál, ranging from some additional Information 
on jQuery Mobile and visual tweaks to our application, to Information on how to package 
an Androld web app using PhoneGap for release to the Android Market. 

In the next chapter, we wlll finish off the book by looking at some potentlal future trends 
in mobile computing. Hopefully, these wlll provide some food for thought, and perhaps 
even give you some Ideas of things you might possibly like to explore In the worid of 
mobile web application development. 




The Future of Mobile 
Computing 

Through the course of the book, we have looked at some code examples and exercises 
that will enable you to build web apps for Android and Chromé OS using the features 
available both on the phone and in the cloud. Whaťs coming though? How are new 
technologies and trends going to change our development approach? 

What is presented in this chapter is a developer's perspective on the potential future of 
mobile platforms and subsequently applications. Of course, the contents of this chapter 
represent oniy one possible view of the mobile future, and many possibilities exist. Given 
current trends in both desktop and mobile computing, though, we certainiy believe that 
we will see components of this chapter implemented over the next few years. 

The Era of Mobile Computing 

The era of mobile computing is upon us. The adoption of web-connected mobile 
devices is one of the fastest-moving trends woridwide. Consumers have become 
accustomed to mobile technology, and for most of us that now includes mobile web 
access. 

This in turn affects the way we will choose to consume and produce information. For 
instance, rather than making sure we are prepared before leaving the house or office for 
things such as appointments, we can now just get up and go. We can access the 
information that we need via our mobile device of choice when we need it, whether that 
is checking the exact time of the meeting or accessing driving directions on how to get 
there. We are definitely becoming accustomed to getting information "just in time" — 
assuming we have good connectivity. 
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A Woridwide Phenomenon 

The take-up of mobile computing is not limited to established markets. In fact, for many 
emerging markets and nations, mobile broadband technologies are being rolled out in 
favor of traditional "landlines" due to the cost-effectiveness of tiie solution. Figuře 13-1 
heips demonstrate this point by showing a graph of monthly traffic for a mobile Twitter 
Client, Tweete (http://m. tweete.net). In thiis particular graph, we can see that the 
majority of traffic for Tweete comes from Indonesia. The primary reason for this is due to 
mobile broadband being more prolific than fixed broadband in countries like Indonesia, 
and thus lightweight mobile clients can get very good traction over more heavyweight 
desktop (and nonoptimized mobile) clients. 



m.tweete.net - Monthly Traffic by Country 
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Figuře 1 3-1 . Emerging markets can provide unexpected opportunities for mobile development. 
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TIP: Many of you may look at the above graph and think — so what? We wouid like to challenge 
that thinking and recommend considering how you couid build mobile applications for emerging 
markets (http://en.wikipedia.org/wiki/Emerging_market) as weil as established 
markets. When doing this, though, you will also have to consider the fact that these nations will 
still have large numbers of simpler mobile devices in circulation. These devices often have web 
connectivity, but don't have the HTIVIL5 support that we have been looking at using over the 
course of the book. ' 

Effectively implement your web application or site with progressive enhancement {dlscusseú in 
the section titled "Embracing Progressive Enhancement") and you may be able to start making I 
inroads into those markets now, and still offer a rich experience with HTML5 features for more 
advanced devices. J 



Death of the Desktop? 

Smartplnones and tablets are really just the tip of the iceberg winen it comes to mobile 
computing. The Mobile Internet Report 

(www.morganstanley.com/institutional/techresearch/mobile_internet_reporti22009. 
html) delivered by Mary Meeker (http://en.wikipedia.org/wiki/Mary_meeker) of 
financial services firm Morgan Stanley makes a number of predictions with regard to 
mobile device penetration and Internet usage of mobile platforms compared with 
desktop platforms. 

Without going into the detail of the report, it suggests that mobile devices will likely be 
the platform of choice for Internet connectivity by about 2014. If this turns out to be an 
accurate estimate, then we need to start designing both sites and applications for the 
mobile web now. 



Embracing Progressive Enliancement 

Progressive enhancement 

(www.alistapart.com/articles/understandingprogressiveenhancement) is a web design 
stratégy in which web designers and coders design web sites and application interfaces 
for the lowest common denominator (within reason) first and foremost. The application 
or site is then enhanced if the visitor's browser is able to support more advanced 
features. JavaScript libraries such as Modernizr (www.modernizr.com) are very useful 
here. 

As to why this is important, take a look at Figuře 13-2, which shows the breakdown of 
mobile-browser market share from August 2009 up until August 2010. 
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Mobile Browser Market Share 
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Figuře 1 3-2. Mobile browser market share from August 2009 to August 2010 



This data (sourced from StatCounter: http://gs.statcounter.com) shows a few things: 

■ Android device usage is on the rise, but is still a small part of the 
market. 

■ While the most popular mobile platform for browsing the web is iOS 
(iPhone, iPod Touch, iPad), there are still many browsers out there in 
active use that do not support HTML5 and CSS3 (e.g., Opera Mini: 
www. opera . com/mobile). 

To assist in showing the current HTML5 vs. non-HTML5 device trending, Figuře 13-3 
has simplified the data into two categories: HTML5 supported and non-HTML5. 
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HTML5 vs Non-HTML5 Mobile Browser Marketshare 
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Figuře 13-3. HTML5 vs. Non-HTML5 mobile browser market share 

As shown in Figuře 13-3, HTIV1L5 devices inave a smaller market share than non-HTML5 
devices. 



NOTE: These statistics aren't what we expected them to be. Over time, the graph actually shows 
less HTML5 compatible devices accessing the Web — and this is extremely suprising, at least at 
first. We think there are a number of potential explanations tor why this is the oase. 

ONE such explanation couid be the recent interest and promotion of the mobile Web. This in turn 
raises consumer awareness of the mobile services that are available online, and thus people with 
existing handsets are accessing mobile web services. 

We wouid be lying if the statistics didn't make us second-guess our certainty of HTIV1L5 adoption 
across a large number of mobile devices. However, this is not the oniy Information we have 
about HTML5 adoption in mobile. Established vendors have provided HTIVIL5 support in their new 
devices. For instance, RIM recently released the BlackBerry Torch and put an emphasis on 
HTML5 support and development options. We believe this is evidence validating the claim that 
HTIV1L5 support in mobile browsers will trend up quickly over the next couple of years. 



While it won't aiways be possible to build web applications and sites using progressive 
enhancennent, it is worth spending some time at the start of a project evaluating the 
potential to support less advanced devices. If you can, you will broaden the reach of 
your application, and, while this book is focused on building Android web apps. 



minimizing the amount of work you have to do to cater for another platform is aiways a 
good thing. 



Mobile Technology Predictions 



The future is far from certain, but it is likely tínat mobile device development and 
arcinitecture will play out in a similar way to desktop computing. TInis being the oase, we 
can probably be brave and make a few predictions. 

NOTE: While there is an obsession with mobile development using native technology at present, 
we strongly believe that history will repeat itself in mobile the same way it did for desktop 
devices. 

This is definitely a risk-vs.-reward situation though, as many roadblocks stand in the way of 
web-oriented mobile development. We believe the community has sent device manufacturers i 
message, though, and that is that web development for mobile is important and something tha 
needs to be prioritized. We also believe they have heard this message, and things are starting l 
change for the better. 



Improvements In Tools and Libraries 

The maturity and availability of both tools and libraries to streamline mobile web 
development is quite limited at the moment. This is changing, though, and we will 
certainiy see a lot more options become available over the next year. One of the most 
promising libraries under development (at the time of writing) is the jQuery mobile 
framework (http : // jquerymobile . com). 

The research that has gone into this library and the focus on broad-spectrum mobile 
device support is very encouraging. From this research, the jQuery team has produced 
what is called the graded browser support (http://jquerymobile.com/gbs) chart, shown 
in Figuře 13-4. 
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Figuře 1 3-4. A screenshot of the jQuery Mobile graded browser support chart 

Hopefully, this will finally provide a mobile web Ul that can be used across devices, 
presenting a web Ul in a device-neutral sense (rather than styling all Ul elements with an 
iPhone look and feel). 

Additionally, as developers, we can oniy hope for the maturity of mobile web 
development tools to improve. While integrated development environments (IDEs) tend 
to get in the way of web development in generál, having suitable testing and debugging 
tools for mobile devices will be important for pushing mobile web development forward 
(in the same way that Firebug contributed to moving web development forward). There 
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is a lot that can be done using desktop browsers such as Chromé, but there really is no 
substitute for device-targeted development tools. 

Changes in Device Arclíitecture 

While Palm is not one of the dominant marl<;et players at the moment, there is a lot that 
can be learned from the way it architected its webOS (http://developer.palm.com) 
platform. From the ground up, webOS has been built with a strong web technology 
focus, providing developers a first-class way of building applications for the platform 
with HTIVIL, CSS, and JavaScript. 

Given this is an Android web apps development book, that might be considered to be a 
strange comment, but leťs look at a couple of industry trends around both mobile and 
desktop computing: 

■ There is a lot of interest with regards to web operating systems as a 
replacement for current desktop operating systems. The 
implementation of a web operating systém is generally achieved by 
using something like Linux to manage the interaction with the 
hardware, and then a web presentation layer providing the operating 
systém "desktop" to the user. Two examples of web operating 
systems are Google's Chrome/Chromium OS 
(www.chromium.org/chromium-os) and Joyenťs Jolicloud 
(www.jolicloud.com). 

■ Modem mobile operating systems are demonstrating continued 
innovation, and they couid quite possibly move to implementing web 
operating systems (as Palm has demonstrated) before broader 
adoption on desktop platforms. 

With those trends and the current Palm webOS architecture in mind, what will mobile 
device architectures look like in the future? Certainiy one possibility is a device 
architecture that has a very strong web flavor to it, and this is shown in Figuře 13-5. 
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Figuře 1 3-5. More mobile devices may incorporate web-centric architectures in the future. 



In this architecture we see a services layer that is exposed to a web Ul. This services 
layer wouid then exposé functionality of the device, very similar to the way that existing 
web applications exposé RESTful web services. 

Using this technique for interacting with the device, combined with the fact that client- 
side web technologies are becoming more powerful, the need to build a mobile 
application interface with native languages shouid definitely become the exception 
rather than the rule. 

This will probably first be evident in an increasing number of mobile applications being 
implemented using web technologies as opposed to native technologies. Once mobile 
web applications are predominant, removing some of the intermediate layers to more 
tightly couple the web Ul to the underlying systém layers will likely be the next step. 
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NOTE: It is doubtful that this will occur on all mobile operating systems, as some will likely 
remain as primarily native development platforms. We wouid estimate, however, that by 2013 
around 30 to 50 percent of mobile operating systém vendors will eitlier release or announce a 
mobile web operating systém and complementary dashboard Ul. 

Interestingly, some momentům is aiready building in this area, with the European Union 
announcing a project called Webinos (http : //webinos . org), which appears to be designed to 
build exactly what is suggested above. 



Coding for Future Architectures 

If things do continue to progress in a web-oriented direction, then there will be very little 
tínat experienced mobile web developers will have to cinange. One exception to that may 
weil be the way we interact with client-side storage. For instance, while HTML5 offers 
three very interesting APls for working with local data, we discovered in Chapter 5 that 
synchronization with online services was not available out of the box. 

Given that mobile devices currently have (and may aiways have) less reliable 
connections than their desktop cousins, it is expected that offline data synchronization 
will become a consumer requirement in the not-too-distant future. Therefore, either the 
HTML5 APls will have to mature to support this requirement, or some alternativě options 
will need to be investigated. A very interesting possibility is the use of an embedded 
CouchDB (http://couchdb.apache.org) instance within the mobile device, which wouid 
serve both the mobile app code and data, and keep that synchronized with the cloud 
automatically. 

Imagine that— an embedded database capable of serving local web applications and 
supporting data, and keeping that in syne with the cloud so when you use the 
application from your desktop everything is synchronized. 



The Internet of Things 

As the number of web-connected mobile devices increases, not oniy does the number 
of potential consumers of Information increase, but also the number of potential 
producers. As discussed back in Chapter 1 , the modem smartphone aiready features a 
large number of hardware sensors, and this opens up some quite amazing possibilities. 

The increasing number of web-connected devices that are present in our society (mobile 
phones and tablets are part of that larger group) has resulted in the creation of some 
interesting research projects and applications that couid influence the way our society 
and we as individuals operáte in the future. 

The collection of these web-connected devices has been termed the Internet of Things 
(http://en.wikipedia.org/wiki/Internet_of_Things), and is weil worth getting involved 
with if you are interested in building some really cool mobile apps. 



Another term that is sometimes used to describe this connected network of devices is 
the Web ofThings (http://en.wikipedia.org/wiki/Web_of_Things). The Web of Things 
and Internet of Things are very similar in that they both involve a massive number of 
interconnected devices feeding real-time information between each other and 
centralized services. The Web of Things model, however, specifies the use of existing 
web communication standards such as HTTP, REST 

(http://en.wikipedia.org/wiki/Representational_State_Transfer), and RSS to enable 
that communication. 



NOTE: From our observations, very few things that happen on the Internet are planned and 
executed in a way that people expect. We believe that the evolution of the Internet of Things will 
be no different, and that it will begin with mobile devices communicating information to web 
applications and sites. This in turn will probably mean that the Web of Things implementation will 
be the one that eventuates, rather than a new way of doing things. Whether that is a good thing 
or not is another conversation, buf suffice to say there will be a significant increase in active web 
clients (desktop plus mobile plus embedded devices) in coming years. It will be interesting to see 
how the current way of doing things scales to that volume of information. 



1 



Hardware Sensor Networks 

As stated previously, mobile devices can have many hardware sensors. Picture those 
sensors being able to (through appropriate privacy controis) share information with 
centralized systems. This couid include data such as weather and traffic information at 
particular locations. 

A couple of examples of existing mobile applications and companion web sites that 
have aiready created sensor networks are Waze (http://waze.com) and NoiseTube 
(www.noisetube.net). Waze is a mobile application that collects GPS readings as you 
drive around your local area. That information is fed back into Waze and used to 
generate mapping information that can be shared among all users. Figuře 13-6 shows a 
screenshot of the Waze mobile interface, which is currently implemented as a native 
interface, but couId easily be implemented as a mobile web application in the future. 
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Figuře 1 3-6. The Waze mobile interface — not a web Ul, but with HTIVIL5 it couid be. 



Waze is an excellent example of an application that makes use of sensors to collect 
information. A more generic example of a platform that supports sensor networks is a 
site/application network called Pachube (www.pachube.com). Figuře 13-7 sinows a 
screenshot of tine front page of Pacinube displaying tine number of sensors contributing 
information back into tine network. These sensors are typically small embedded devices, 
but couId be mobile devices just as easily. 
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Figuře 1 3-7. Pachube is a site with APl-supporting distributed sensor networks. 



The Human Sensor 

In addition to the applications that focus on using device sensors to collect and 
communicate Information, consider the phenomenon known as the Human Sensor. This 
is where individuals are reporting information about their surroundings back into a 
centrál systém for processing. 

An excellent example of this is a mobile application and supporting web site called 
Ushahidi (www.ushahidi.com). This application is designed to allow individuals to submit 
location-specific reports to a centrál Ushahidi server. Figuře 13-8 shows some device 
shots from the current Ushahidi Android application, which like Waze is currently a 
native application. 
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Figuře 13-8. Ushahidi is a crowdsourcing crisis information systém with mobile clients. 



As can be seen in the device sliots of Ushahidi, it marl<ets itself as an application that 
does a particularly good job of collecting crisis information. In fact, the Ushahidi platform 
was used to assist with the reliéf efforts after the earthquakes in Haiti. 

In addition to specialized applications like Ushahidi, things like geosocial networking (as 
covered in Chapter 10) are also good examples of sensor networks driven from human 
interaction. 



Summary 

in this chapter, we have had a look at some trends in mobile computing and how mobile 
web development fits into the picture. There are many opportunities opening up in the 
mobile space, both in established and emerging markets. 

Additionally, with more and more devices coming online, there are some very interesting 
projects that can be explored both for mobile app development and in the cloud. 

The best thing any developer can do right now is to get involved, and, while we wouid 
highiy recommend working with mobile web technologies, the more important thing is to 
get started somewhere. Hopefully, over the course of the book you have been exposed 
to both the basics of mobile web development and some more advanced topics, plus 
some ideas about the kinds of applications you couid build. 

Now, get out there and build great mobile apps. 



Appendix 



Debugging Android Web 
Apps 

Debugging JavaScript applications and libraries is something that traditionally haunts 
web developers. You may Inave read fórum comments or articles by people wino have 
been less than enthusiastic about going down this mobile web application path. We wili 
admit that it is more difficult than debugging an application that has a nice, shiny IDE; 
however, with the right tools and techniques, you can learn to track down and fix 
JavaScript errors with relative ease. Before you debug your scripts, though, you can use 
certain tools to scan and check your code and report any issues. This is a huge time- 
saver in the development process. in this appendix, we will see how we can increase our 
productivity and at the same time improve our code quality. This is an essential aspect 
of software engineering, especially when you start to work on bigger projects. A good 
starting point is the JSLint tool. 

JSLint: Prevention Is Better Than Cure 

JSLint (http://jslint.com) is a tool created by Douglas Crockford to assist developers 
in writing their JavaScript code consistently. JSLint is a code quality tool, and it can be 
run either online at the JSLint web page or from the command line. Depending on the 
text editor you are using, you may even be able to get a plug-in/extension that 
automatically runs JSLint over your code each time you save— which is very handy. 

JSLint checks for common mistakes that can occur during coding, such as missing 
semicolons and portions of "dead code," which is code that will nevěr be executed 
because iťs unreachable. It will also warn you about code that runs without errors but is 
considered bad practice or violates a style convention, and it will produce a report for 
you that lists all the problems. In generál, JSLint will help you fix code errors faster, as 
weil as learn good JavaScript practices, especially if you are a novice. 

In most cases, using the online JSLint tool is sufficient, and iťs recommended when 
working through the sample code in this book. In the online JSLint tool, you paste your 




code into an input text area and then just press a button to generate the report. But, if 
you are working on a big project with a team, at a certain point you may want to provide 
some automation in your build and release process, instead of clneci^ing it manually 
eacli time by pasting it into tlie online tool. For tinis type of situation, there are some 
options available, including a plug-in for Hudson, a continuous-build server that 
automatically retrieves from source control servers, tests and distributes your code (see 
http://hudson-ci.org), and more basic basin scripts tínat can be integrated to crone 
jobs, for instance. Another option is to use Mozilla Rhino, which is a Java-based 
JavaScript interpreter (see www.mozilla.org/rhino). You can pass your script and the 
JSLint library to Rhino as arguments, and Rhino will run JSLinťs check process. And 
because iťs a Java program, Rhino is very easy to integrate with other Java-based 
frameworks, including the famous Ant build tool (discussed in more detail in Chapter 9; 
see http : //ant . apache . org). Check this blog post to see how Ant and JSLint can be 
combined: www. ifisgeek.com/2009/05/05/running-jslint-in-automated-build- 
scripts. 

However, even if you take all these precautions to produce weil-written, robust code, 
you'll still have to confront the debug process at some point, especially if the complexity 
of your script is growing or if you're dealing with third-party libraries where the 
implementation is unknown by you. The following sections discuss some of your 
debugging options. 

Debugging with the Google Chromé Developer Tools 

The maturity of tools for working with JavaScript has improved dramatically over the last 
few years. The first notable mention goes to Firebug for enabling the debugging of so 
much brilliant code during the course of the Ajax movement (see http://getfirebug.com). 
Secondly, and more importantly for us working in the Android mobile space, Chromé 
and the Chromium project (http://chromium.org) are taking that tool maturity even 
further. 

The main advantage to working with the Chromé developer tools 
(www.chromium.org/devtools) in Chromé or Chromium is that you'll be working once 
again with the WebKit rendering engine, which means that your JavaScript code will be 
interpreted the same way. This provides developers with some common ground 
between the desktop and mobile platforms for identifying and debugging problems. 

We will have a look at some of the most useful tools now. The tools suitě is integrated 
with the Chromé browser (www.google.com/chrome), so just be sure to have it installed 
before moving on. 

Catching Messages and Errors in tlie Console 

The developer tools console is probably the least advanced of the tools available in the 
suitě, but almost certainiy the most useful. Quite simply, the console is both a reporting 
interface and a manuál code execution tool. Figuře A-1 shows an example of how the 
developer tools console appears after running the following snippet of code: 



<html> 
<body> 

<script type="text/javascript"> 
// write some console messages 
console. debug( "debug message" ) ; 
console. info("info message"); 
console. warn("warning message"); 
console . error ( "error message" ) ; 

// throw an exception 

throw new Error("This is a test exception"); 

</script> 

</body> 

</html> 
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Figuře A-1 . The Chromé developer tools console aňer running our console test snippet 



The console displays messages that you placed in JavaScript code using console 
debugging. Additionally, it shows the location of any uncaught exceptions that have 
been raised while executing a script. 

To see an error in the context of the code that it was running against, simply click one of 
the underlined files displayed on the right of the screen. You will then be taken to the 
Resources section, which shows where the warnings/errors were generated from. 
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Debug and info messages aren't displayed. Figuře A-2 shows an example of the 
Resources screen. 



Developer Tools - http;//localhost:8080/5nipf>ets/01/consoletest.hur. 



Elements Resources ' Scripts Timeline Profiles Storage Audits Console 



5earch Resources 



I Dacum»nts Siylesheeu lmag*s Scripis XHR Fonts Othcr 



CO 



<htfil> 
<body> 

<script type="text/iavascript"> 
// write some console nessages 
console. debug ("debug message") ; 
console.inŤoCirto ^Eiíage"); 
COnso Le . Ví a rn í " •' I 1 1 1 ■:: 5 age" I J 

warning message 



age") i 



// thro. 
throw ni 



ror'! " I - - - • v-^pt ion" 1 : 

^ncauqht Error TTiis is a test KceptiflS| 



</script.' 
</body> 



□ >= \ ^ \ S \ Sort by Response Time t 



02 _1 



Figuře A-2. The Resources section of the developer tools shows warnings, errors, and exceptions In context. 



For the most part, the functionality provided by the console and Resources view is 
adequate for catching the small and frustrating errors that can occur when working with 
JavaScript. For example, try to insert your console statements at strategie places and 
using the right log type ("warning," "info," "error" or "debug"). Your catch closure shouid 
aiways log the reason why it was caught. Good log output is aiways very instructive and 
helpful before using heavier tools such as the debugger, which will be explained now. 



Script Debugging 

Every now and again, you may hit a problém that is either difficult or inefficient to solve 
using logging to the console in isolation. For a long time, the console method was the 
best that JavaScript developers couid hope for, but more recently both Firebug and the 
Chromé developer tools have provided Interactive debugging features. This enables the 
creation of breakpoints, watches, and other goodies that are usually reserved for IDEs 
and compiled code. Figuře A-3 shows the script debugger, and, while we won't go into 
an in-depth tutoriál on its use here, we will just explain the basic concept of a 
breakpoint. 



A breakpoint functions just like the Pause button on your DVD player. It stops the code 
from running at whatever point you set it. You can set a breakpoint anywhere you 
want— just click the line number label, and the code will pause when it reaches the line. 
Why is it useful to pause code execution? WeII, at the nnoment you enter a breakpoint, 
you get an instant picture of the statě of your script, including all the variables' states. 
This is very useful, for example, to see whether a variable has been set yet or is still 
null. You can even change the value of a variable at runtime. You can also check the 
call stack, which shows the hierarchy of function calis; this can be very handy when 
you're working with complicated flows and you want to know exactly who is calling 
whom. For example, if you set a breakpoint inside the function retrieveTaskDetails() 
which was called by the function getNewestTask(),you will be able to see this 
arborescence in the debug tool. 

After inspecting your script, you have different options: step over, step in, and stop. 
Stepping over is just like hitting the Play button on your DVD player after a video has 
been paused— your script will continue to run until it reaches the end or another 
breakpoint. Stepping in can be used if your breakpoint is on a code line that calIs 
another function. You can step into this function, and the script will freeze at the first 
statement of this function. Of course, you can stop running the script at any time by 
clicking the Stop button. 



Developer Tools - http://localho5t:8080/5nippets/0iyconsoletest.litml 

, ,m ^1 g 1^ 



E]ements Resources ' Scripts ' TimeJme Prales Storage Audits Cansole 
•4 f chrome-extension://eákacpaí}cpapndc' « 



/♦! 

* jOuery JavaScript Library \i\.A.2 

* fittp: //j query. coni/ 
♦ 

* Copyright 2fll0, John Resig 

* Dual licensed under the MIT or GPL Version 2 licenses. 
+ ^^ttp://jquery. org/license 

4- 

* IncLudes Sizzle.]? 

* hittp://sizzlejs. cam/ 

* Copyright 2012, The Dojo Foundation 

+ Released under the MIT, BSD, and GPL LicerrsES. 

* 

* Date: Sat Feb 13 22:33:4B 2018 -0S0B 

(function! window, undetined ) { 

// Define a local copy of jOuery 

var jCJuery = tunctiDnl selector, context } C 

// The jOuery object is actually jiist the init ca 
return new jOuery. f rt. inití selettor, context 1; 

}, 

// Map over jOuery in case oi overwritB 
_jOuery = window. jQuery, 

// Map over the $ in case of overwrite 
_J = window. $ , 

// Use the correct document accordingly with window a 
document = window. document, 

// A centrál reference to the root jOiieryídocufnent) 
roĎtjQuery, 



Search Scripts 
II t t ^ 

▼ Watch Expressions 

jOuery: ReferenceError: jQu-. 

Add Etefresh 



▼ Stope Variables 



▼ Breakpoints 



0 cbrom*-eKlensiori.//eakacpaucpůpndíífti 
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□ Debug 



> Workers 
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Figuře A-3. The script debugger provides breakpoints and variable watches for more trying times. 
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NOTE: You'll often hearthe statement "Smart developers clon't use the debugger." The idea 
behind this is that, if you put your console log statements in tlie rigiit places and trace the right 
info, it won't be necessary to use the debugger, and you'll be spared a lot of time (checking your 
console output is quicker than stepping into your code). The fact Is, however, that you won't 
aiways be testing your own code, and you'll sometimes have to test code that you wrote a long 
time ago and don't remember the details of — In these cases, the debugger offers some flexibility 
for seelng exactly whaťs happening. 



Inspecting the DOM with the Elements Tab 

It is pretty easy to end up with typos in HTML, and sometinnes strange things can 
happen in terms of your layout— especlally when you are modifying the DOM (Document 
Object Model) at runtime. To see what the current statě of your HTML Is, the Elements 
tab In the developer tools is Invaluable. Figuře A-4 shows an example of the Elements 
tab. 



Developer Tools - Íittp://10.1.1.100:8080/snippet5/04/todoli5t.html 

af 



Elements ' Resources Scripts Timelíne Profites Storage Audits Console 



Sťarch Elements 



r <htfnl> 
► <sty le>-.</ & ty Le> 
<style>-NFClas5 { backgroLind-coLor: red; ></styLe> 
<headl>-</head> 
▼ «íbody> 

<ul icí="mefiíu"></ul> 
▼ <diu id-"niain" cla5s="vievi"> 
■:hl>Tí> Oo H5t-;/hl> 
T-ídív class="task" styLe='"display: block; "> 
p •;li3>_</h3> 

<p <:la5 5="ta5k-de5criptiDn"></p> 
^ <p class=" task-due":'_.</p> 
IKul c'Lass="ta5k-actÍDns">_</Ljl> 
</div> 

► 'íul c las s="buttĎns"5_</u L> 
*/ditf> 

► <div id="alltasks" £;lass=" vieM"»_.«/div> 
k- <div i[J="ad[l" c Lass=" w iew">-.-e:/ditf> 
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f ont-f amilyt Arial; 
' margin: flpx; 
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rgin ! 9 pK} 
display: block; 

^ Metrics 

► Properties 

► Event Listcners 



□ >E html body 



Figuře A-4. 7776 Elements tab shows the current statě of the mobile app's HTML 



lebugging 



is 



When an element is selected in the HTML pane on the left, details of the element 
(including applied styles, bound event listeners, etc.) are displayed on the right. 
Additionally, you can use the DOM inspector 

(http://en.wikipedia.org/wiki/DOM_Inspector) to dynamically apply styles and change 
properties at runtime to experiment with what impact a change to a stylesheet wouid 
actually have before implementing it. If you change a property at runtime, be aware that 
it will oniy be temporary; when your page is reloaded, this property will return to its 
originál value, so don't forget to update and save your source file if you find a suitable 
property for an element. 



Debugging with the Android Debug Bridge 

While Chromé is invaluable for testing your web apps, spending time in the Android 
emulátor is crucial to seeing how the application will actually behave once deployed to a 
device. 



NOTE: In addition to running tests in the emulátor, it is also important to test your application on I 
an actual device before deploying either to a publicly accessible web site or the Android ■■■■H 
marketplace (if you are using a bridging framework). Information on how to configure USB 1 
debugging to gain similar debugging features as described below can be found at the following J 
^^web page: http://developer.android.com/guide/developing/device.html. 

Once you start working with the browser in the emulátor or on an actual device, and you 
attempt to debug your application, it will start to feel like you are back working in the 
early versions of Internet Explorer. JavaScript errors occur silently, and the Android 
browser doesn't even have a console similar to mobile Safari on the iPhone. 

Thaťs certainly how it appears on the surface, but iťs not as bad as it seems. By using 
the adb tool that comes packaged with the Android SDK, you can actually see 
JavaScript errors that occur within the browser on the emulátor. 

Running adb logcat will generate output similar to that displayed in Figuře A-5. In this 
particular example, the events pertaining to JavaScript console events have been sent 
from the WebCore application. It can be useful to see what other events are going on in 
the emulátor, though — such as when garbage collection and other system-level events 
are occurring. 



Terminal — adb — 80x24 



Uing back to default line: 744 source: http://train.tripplanner.racq.CQin.aLi/iiiob 
ile/scripts/tileS.js 

D/dalvikviii( 176): GC freed 4295 objects / &63112 bytes in 180ms 
D/WebCore ( 176): Console: populating grid, x shift = 0, y shift = 2t line: 744 
source: http://train.tripplanner.racq.com.aU/niobile/5cripts/t i leS.js 
D/dalvikvm( 176): GC freed 3470 objects / 368264 bytes in llSms 
D/dalvikvmí 176): GC freed 5853 objects / 818136 bytes in 119rtis 
D/dalvikvm( 176): GC freed 5495 objects / 312720 bytes in 99ms 

D/WebCore ( 176): Console: Not able to tap element, line: 290 source: http://tr 
ain. t ripplanner. racq. c on. au/mobile/ j qtouch/j qtouch. j s 

D/WebCore ( 175): Console: populating grid, x shift = 0, y shift = B line: 744 
source: http: //t rain. t ripplanner . racq. com. au/mobile/scripts/tileS. j s 
D/dalvikwm( 176): GC freed 2628 objects / 224864 bytes in 108iiis 
W/KeyCharacterMap( 175): No keyboard for id 0 

W/KeyCharacterHapí 175): Using default keymap: /system/usr/keychars/qwerty. kcra. 
bin 

V//IInputConnectlonWrapper( 52): showStatusIcon on inactive InputConnection 
D/dalvikym( 93): GC freed 7461 objects / 406792 bytes in 316ms 
D/WebCore ( 176): Console: Not able to tap element, line: 290 source: http://tr 
ain. t ripplanner. racq. com. au/mobi Le/j qtouch/j qtouch. j s , 
D/HebCore ( 175): Console: populating grid, x. shift = 0, y shift = B line: 744 \J 
source: http://t rain. t ripplanner. racq. com. au/mobi le/scripts/t i leS.js 
D/dalvikvm( 176): GC freed 10128 objects / 894896 bytes in 148nis 
D 



Figuře A-5. Output from adb logcat is extremely useful when debugging JavaScript in the emulátor. 

If you find this log a bit too noisy, tliere is a tip to extract oniy tlie lineš from the 
WebCore process: 

adb logcat WebCore: * *:S 
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#marker-detail screen, 311 
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ant debug install, 318 
ant debug mode, 210 
Ant debug target, 199 
ant release command, 332 
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APls (application programming interfaces) 
Geolocation, W3C specification for, 

118-122 
HTML5 storage, 47-63 
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appearance property, 31_ 

application definition, 324 
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APls 
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are method, 142 
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authenticated event, 303 
authentication process, in Moundz, 323-324 
autohiding, URL bar, 25-26 
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AVDs (Android Virtual Devices), creating, 
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body tag, 26, 264, 289, 327 
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breakpoint, 357 
Bridge Code, 250 
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Camera.DestinationType.FILE_URI value, 
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camera. getPicture method, 206 
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canvas, 129-131 

animations for, 1 37-1 48 
creating loops, 1 37-1 38 
and device DPI, 1 42-1 48 
drawing frames of, 1 38-1 42 
drawing interactively to, 1 32-1 37 
by mouše events, 132-134 
by touch events, 134-137 
paths, 141-142 
transformations for, 1 53-1 60 
canvas tag, 130 
car-easing.js file, 150 
car.js file, 143 
carX variable, 152 
challenge directory, 271 
changeVersion method, 62 
ChangeViewAction class, 117 
child-screen class, 180 
child-screen div, 181 
Chromé developer tools, 58-59, 223, 

352-353 
class attribute, 33 
className property, 117 



clear handler, 54 
clear method, 48 
clearTimeout function, 38 
clearWatch method, 240 
click events, 285, 287 
client-side databases, saving items with, 
56-61 

cloud Services, synchronizing with, 95-1 1 0 
Google App Engine service, 98-1 02 
making desktop interfaces, 110 
online storage options, 95-97 
updating user interface for, 1 03-1 06 
Cloud to Device Messaging (C2DM), 5 
com/phonegap/Sample directory, 212 
com/prowebapps/maptest directory, 212 
com.phonegap.Sample reference, 212 
com.phonegap.Sample.Sample class, 212 
completionCallback argument, 55 
com.prowebapps.maptest, 212 
connection status, detecting, 126-127 
connectivity, 2^3 

console, debugging with Google Chromé 
developer tools, catching 
messages and errors in, 352-354 

content://moundz, 325 

context.clearRect method, 141 

context.restore( ) method, 155 

context.save( ) method, 141 , 155 

Coordinates type, 118 

coords property, 118 

corner rádius property, 112 

CREATE TABLE statement, 61^ 

create-task-form.html file, 84 

createFooter function, 294, 297 

createHeader function, 292-294 

creationCallback argument, 55 

Crockford, Douglas, 50 

css directory, 263, 289 

css/jo.css file, 264 

CSS styles, for mobile HTML forms, 27-39 

with different screen sizes, 34 

and orientation changes, 35-39 

page title appearance, 33 
CSS3 definitions, 30-33 

appearance property, 31_ 

border-radius property, 31_ 

box-shadow property, 32 

gradient fill style, 32-33 
currentResource variable, 309, 31 1 
currentTasks variable, 86 
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data-* attributes, 282 
data-icon attribute, 282 
data-iconpos attribute, 306 
data-id attribute, 282 
data-role attributes, 282, 293 
data-role types, 285 
data-role="fieldcontain" attribute, 310 
data transfer object (DTO), 57 
databaseid argument, 55 
databases, local and storage, 5 
Date( ).getTime( ) function, 152 
Date object, 61 
DATETIME columns, 61_ 
DATETIME type, 61_ 
debugging, 351-358 

with Android debug bridge, 357-358 
with Google Chromé developer tools 
catching messages and errors in 

console, 352-354 
inspecting DOM with Elements tab, 

356-357 
script debugging, 354-356 
with JSLint, 351-352 
declarative frameworks, comparison of 

Mobile Ul frameworks, 257 
DEFAULT category, 325 
default theme file, 273 
define function, 69 
DELETE operation, 55 
démos directory, 271 
deploying apps, Moundz, 299-331 
and Android intents, 324-326 
authentication process in, 323-324 
handling intents with PhoneGap plug-in, 

326-331 
login screen for, 299-305 
modifying application permissions, 

321-323 
navigation layout for, 305-307 
packaging for release, 331 
packaging with PhoneGap, 316-321 
resource details screen for, 307-314 
using Geominer for resource tracking in, 
314-316 
description argument, 55 
desktop computing, vs. mobile computing, 
339 

desktop interfaces 

deploying applications on cloud 
Services, 1 09-1 1 0 



querying jsonengine instances, 1 07-1 09 
dešti nationType value, 207 
detailCard, 268 
details_panel, 297 
dev_appserver command, 100 
developer tools, Chromé, 58-59 
development environment, 8-16 
emulators for, 11-16 
creating AVDs, 12-14 
starting, 14-16 
text editors, and working directories, 8^9 
web server, 9-1 1 
Mongoose, 9-10 
SD card images, 11_ 
working directories for, and text editors, 
8-9 

device arclíitecture, 344-346 
device-dpi setting, 143 
deviceReady event, 328-329 
directories, and text editors, 8^9 
displayErrors function, 41_ 
display:none attribute, 105 
div elerments, 257, 274, 283, 302 
dockedltems array, 292 
_doc:taskJson,_docld:task.id parameter, 
102 

DOlVI (Document Object Model), inspecting 

witli Elerments tab, 356-357 
DOMTimestamp type, 118 
dots per inch (DPI), for devices, 1 42-1 48 
double type, 119 

downioading PhoneGap, 1 94-1 95 
DPI (dots per inch), for devices, 1 42-1 48 
drawable-hdpi folder, 320 
drawable-ldpi folder, 320 
drawable-mdpi folder, 320 
drawing interactively, to HTML5 canvas, 
132-137 

by mouše events, 132-134 

by touch events, 134-137 
drawTo method, 131 
drawWheel function, 158 
drops.html file, 137 
drops.js file, 137 
DTO (data transfer object), 57 
due field, 61 
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Elements tab, inspecting DOM wlth, 
356-357 



emulátor @android_web_apps command, 
200 

emulátor command, 201 
emulátor executable, 200 
emulators, 11-16 

creating AVDs, 12-14 

starting, 14-16 
enableHighAccuracy option, 240 
endAngle variable, 158 
errorCallback argument, 55 
estimatedSize argument, 55 
executeSql method, 55 
Ext.Button class, 293 
Ext.Button object, 293 
Ext.Panel, 290-291 

extraClauses parameter, getTasks function, 

79-80 
Ext.setup function, 290 
Ext.Toolbar class, 293-294 

FF 

fabric.js library, 142 
FALLBACK keyword, 124 
FALLBACK. NETWORK keyword, 124 
features, 7, 148 

feedback, for form validatlon, 40-46 
fill method, 142 
filIRect method, 155 
findResources function, 236-237, 240 
for loop, 101-1 02, 236 
form elements, for mobile HTML forms, 
26-27 

form validatlon, for mobile HTML forms 

overview, 39-40 

providing feedback for, 40-46 
foursquare app, 118 
Foursquare network, 163 
frameworks/challenge/jQueryMobile 

directory, 300 
frequency option, 205 
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gather function, 315 
gatherResource function, 315 
geolocation 
overview, 3-4 

tracking position wlth, for Moundz, 
238-241 



Geolocation APls, W3C specification for, 

118-122 
geolocation div element, 119 
Geominer API 

connecting to sociál APls using, 

230-231 

finding resources with, for Moundz, 
234-237 

in Moundz, using for resource tracking, 
314-316 

GeoMiner application, 54 

geominer module variable, 251 

GEOMINER.Bridge object, 252, 303, 331_ 

Geosocial networking, 1 63-1 64 

get function, 108 

GET method, 107 

getAction function, 92-93 

getAnchor method, 70 

getContext method, 131 

getCurrentPosition method, 238, 240 

getDaysDue method, 81 

getIncompleteTasks method, 80 

getitem method, 48, 51 

getMarkerIndex function, 187 

getMostImportantTask method, 80 

getPicture method, 206 

getTasks function, 78-80 

getTaskslnPriorityOrder method, 80 

getViewActions function, 92-93 

GitHub repository, 158 

Global Positioning System (GPS), 3 

Google App Engine service, 98-1 02 

choosing synchronization mode for, 100 
deploying jsonengine instances locally, 
99-1 00 

sending offline data to jsonengine 
instances, 101-102 
Google Chromé developer tools, debugging 
with 

catching messages and errors in 
console, 352-354 

inspecting DOM with Elements tab, 
56-357 

script debugging, 354-356 
Google Maps API, 1 65-1 66 

adding markers to, 169-171 

showing marker detail, 171-173 
google. maps. LatLng object, 240 
google. maps. Map class, 166 
google. maps. Marker class, 170 
goTo method, 276 



gotoPosition function, 251, 295 
Gowalla network, 161, 163 
GPS (Global Positioning System), 3 
gradient fill style, 32-33 
Gradient type parameter, 32 
Gruber, John, 25 
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h1 element, 66, 177 
h1 .fancy style, 66 

hardware sensor networks, 347-349 

hardware sensors, 4-5 

has-detail class, 183 

head section, 30 

heading property, 119 

height parameter, 24 

Hello World example, 16-19 

helloworld.html file, 17, 19 

hide function, 115 

high DPI mode, 145 

Home Screen 

requirements of storage module for, 
78-81 

wiring up, 82-84 
Horizontál offset parameter, 32 
hsla color function, 245 
hsla scheme, 245 
HTML elements, 289 

HTML files, multipage apps with single file, 
65-72 

ViewAction class for, 70-72 
ViewManager module for, 68-70 
html function, 108 

HTML5 (HyperText Markup Language 5) 
storage APls, 47-63 
local vs. session storage, 54 
saving objects using JSON, 49-54 
Web SQL databases, 54-63 

saving items with client-side, 56-61 
versioning and upgrades, 62-63 
Human Sensor, 349-350 
HyperText Markup Language 5 storage 
APls. See HTML5 storage APls 

ri 

Icon.png file, 319 
icons, custom, 1 85-1 86 
ifconfig command, 17 



IMEI (International Mobile Equipment 

Identity), 97 
img directory, 185, 214 
img tags, 287 
Indexed database, 47 

index.html file, 215-216, 233, 237, 257, 263, 

282, 300, 327-328 
index.html initialize function, 238 
index.html page, 246 
info div element, 104 
init method, 252, 259, 290, 329, 331_ 
initial-scale parameter, 24 
initialize function, 176, 190, 237, 290 
initMap function, 166, 1 68-1 69 
initScreen function, 187, 264, 274, 283, 

290-291 , 31 1 
INSERT operation, 55 
install target, 199 
intent-filter, 324-325 
intents, in Moundz 

handling with PhoneGap plug-in, 

326-331 
overview, 324-326 
interactivity, 129-1 60 

for canvas animations, 132-160 
creating loops for, 137-138 
creating realistic movement, 1 49-1 52 
and device DPI, 142-148 
drawing frames of, 1 38-1 42 
drawing images for, 1 42-1 48 
by mouše events, 132-134 
by touch events, 134-137 
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